Skip to content

The only tool you need to know what is happening and how to fix it.

updated docs for logs and the website - added logs page

dduxb257c5f56933
diff --git a/docs/pages/client/cloudflare/index.mdx b/docs/pages/client/cloudflare/index.mdx
index 153b531b..e6d08538 100644
--- a/docs/pages/client/cloudflare/index.mdx
+++ b/docs/pages/client/cloudflare/index.mdx
@@ -1,8 +1,10 @@
# Cloudflare Workers
-Cloudflare Workers has built-in observability that can export traces via OTLP. No SDK or code changes are needed in your Worker — just configure a destination in the Cloudflare dashboard and enable it in your `wrangler.jsonc`.
+Cloudflare Workers has built-in observability that can export traces and logs via OTLP. No SDK or code changes are needed in your Worker — just configure a destination in the Cloudflare dashboard and enable it in your `wrangler.jsonc`.
-## Step 1: Create a destination in the Cloudflare dashboard
+## Traces
+
+### Step 1: Create a traces destination in the Cloudflare dashboard
Navigate to **Compute (Workers) → Observability → Destinations**, then click **"+ Add Destination"**.
@@ -11,15 +13,15 @@ Navigate to **Compute (Workers) → Observability → Destinations**, then click
Fill in the following fields:
- **Destination Type**: Traces
-- **OTLP Traces Endpoint**: `https://cloud.tracewayapp.com/api/otel/v1/traces` (or your self-hosted equivalent)
-- **Destination Name**: `traceway`
+- **OTLP Endpoint**: `https://cloud.tracewayapp.com/api/otel/v1/traces` (or your self-hosted equivalent)
+- **Destination Name**: `traceway-traces`
- **Custom Header**: `Authorization` = `Bearer <project_token>`
Replace `<project_token>` with your project token from the Traceway dashboard under **Project Settings**.
![Add Destination form](/cloudflare-add-destination.png)
-## Step 2: Enable in wrangler.jsonc
+### Step 2: Enable traces in wrangler.jsonc
Add the `observability.traces` configuration to your `wrangler.jsonc`, referencing the destination name you created above:
@@ -28,7 +30,7 @@ Add the `observability.traces` configuration to your `wrangler.jsonc`, referenci
"observability": {
"traces": {
"enabled": true,
- "destinations": ["traceway"],
+ "destinations": ["traceway-traces"],
"head_sampling_rate": 1
}
}
@@ -37,7 +39,49 @@ Add the `observability.traces` configuration to your `wrangler.jsonc`, referenci
Set `head_sampling_rate` to a value between `0` and `1` to control what fraction of requests are traced. Use `1` to trace every request.
-## Step 3: Deploy
+## Logs
+
+Logs work exactly like traces — create a second destination in the dashboard, add a second block to `wrangler.jsonc`, and redeploy. No Worker code changes.
+
+### Step 1: Create a logs destination in the Cloudflare dashboard
+
+Back in **Workers → Observability → Destinations**, click **"+ Add Destination"** a second time and fill in:
+
+- **Destination Type**: Logs
+- **OTLP Endpoint**: `https://cloud.tracewayapp.com/api/otel/v1/logs` (or your self-hosted equivalent)
+- **Destination Name**: `traceway-logs`
+- **Custom Header**: `Authorization` = `Bearer <project_token>`
+
+Use the same project token as the traces destination.
+
+### Step 2: Enable logs in wrangler.jsonc
+
+Add the `observability.logs` block alongside `observability.traces`:
+
+```jsonc
+{
+ "observability": {
+ "traces": {
+ "enabled": true,
+ "destinations": ["traceway-traces"],
+ "head_sampling_rate": 1
+ },
+ "logs": {
+ "enabled": true,
+ "destinations": ["traceway-logs"],
+ "head_sampling_rate": 1,
+ "persist": false
+ }
+ }
+}
+```
+
+- `head_sampling_rate` (0 to 1) controls what fraction of logs are exported. Use `1` to export every log.
+- `persist: false` disables Cloudflare's own dashboard log storage to reduce billing when Traceway is your primary destination. Set to `true` (or omit) if you still want to view logs in the Cloudflare dashboard as well.
+
+When both traces and logs are enabled, each log carries the `trace_id` and `span_id` of the request that produced it — so Traceway shows those logs on the matching trace detail page automatically.
+
+## Deploy
Deploy your Worker:
@@ -45,4 +89,6 @@ Deploy your Worker:
npx wrangler deploy
```
-Traces will appear in Traceway automatically.
+Traces and logs will appear in Traceway automatically.
+
+See [OTel Logs](/client/otel/logs) for the full OTLP logs mapping and severity reference.
diff --git a/docs/pages/client/otel/_meta.json b/docs/pages/client/otel/_meta.json
index 2c242b8a..710d171c 100644
--- a/docs/pages/client/otel/_meta.json
+++ b/docs/pages/client/otel/_meta.json
@@ -1,5 +1,6 @@
{
"index": "Overview",
"traces": "Traces",
- "metrics": "Metrics"
+ "metrics": "Metrics",
+ "logs": "Logs"
}
diff --git a/docs/pages/client/otel/index.mdx b/docs/pages/client/otel/index.mdx
index 55d9784c..34441ba4 100644
--- a/docs/pages/client/otel/index.mdx
+++ b/docs/pages/client/otel/index.mdx
@@ -1,6 +1,6 @@
# OpenTelemetry Integration
-Send traces and metrics from any OpenTelemetry-instrumented application to Traceway — no vendor SDK required.
+Send traces, metrics, and logs from any OpenTelemetry-instrumented application to Traceway — no vendor SDK required.
[OpenTelemetry](https://opentelemetry.io/) (OTel) is the industry-standard, vendor-neutral framework for collecting telemetry. If your app already uses OTel, you can point it at Traceway with a few lines of config. If you're starting fresh, any OTel SDK will work.
@@ -8,7 +8,7 @@ Send traces and metrics from any OpenTelemetry-instrumented application to Trace
1. **Instrument your app** with an OpenTelemetry SDK (or auto-instrumentation).
2. **Export via OTLP/HTTP** — configure the SDK (or an OTel Collector) to send data to your Traceway instance.
-3. **Traceway maps the data** — spans become endpoints and traces; metrics appear on your dashboards.
+3. **Traceway maps the data** — spans become endpoints and traces, metrics appear on your dashboards, and logs are indexed and linked to their originating traces.
## Supported Languages
@@ -31,6 +31,7 @@ Any language with an OTel SDK can export to Traceway. Here are the most common o
| **Endpoint** | `https://<your-instance>/api/otel` |
| **Traces path** | `/v1/traces` |
| **Metrics path** | `/v1/metrics` |
+| **Logs path** | `/v1/logs` |
| **Auth header** | `Authorization: Bearer <project_token>` |
| **Protocol** | OTLP/HTTP (Protobuf or JSON) |
| **Compression** | Gzip supported (`Content-Encoding: gzip`) |
@@ -80,6 +81,8 @@ service:
exporters: [otlphttp]
metrics:
exporters: [otlphttp]
+ logs:
+ exporters: [otlphttp]
```
## Connection Page
@@ -92,3 +95,4 @@ Your Traceway dashboard includes a **Connection** page with a ready-made config
- [Traces](/client/otel/traces) — how OTel spans map to Traceway concepts
- [Metrics](/client/otel/metrics) — supported metric types and histogram handling
+- [Logs](/client/otel/logs) — export OTel logs and link them to your traces
diff --git a/docs/pages/client/otel/logs.mdx b/docs/pages/client/otel/logs.mdx
new file mode 100644
index 00000000..2b6350ae
--- /dev/null
+++ b/docs/pages/client/otel/logs.mdx
@@ -0,0 +1,194 @@
+# Logs
+
+Traceway ingests OpenTelemetry logs via the OTLP/HTTP protocol at `POST /api/otel/v1/logs`. Logs emitted inside an active span context are automatically linked to the trace and span that produced them.
+
+## Log Record Mapping
+
+Each OTLP `LogRecord` maps to a Traceway log as follows:
+
+| OTel Field | Traceway Field | Notes |
+| ------------------------------- | --------------------- | --------------------------------------------------------------------- |
+| `TimeUnixNano` | Timestamp | Falls back to `ObservedTimeUnixNano` if zero |
+| `TraceId` (16 bytes) | Trace ID | Hex-encoded |
+| `SpanId` (8 bytes) | Span ID | Hex-encoded |
+| `SeverityNumber` (1-24) | Severity Number | Also used to compute Severity Text when text is empty |
+| `SeverityText` | Severity Text | Uppercased; when empty, derived from `SeverityNumber` (see below) |
+| `Body` | Body | Strings stored as-is; arrays and maps are JSON-encoded |
+| `Resource.service.name` | Service | Required for the Logs page service filter |
+| Resource attributes | Resource Attributes | Stringified; array and map values are dropped at attribute level |
+| Scope name / version | Scope Name / Version | |
+| Scope attributes | Scope Attributes | Same stringification rules as resource attributes |
+| Log record attributes | Log Attributes | Same stringification rules |
+
+## Severity Fallback
+
+When an SDK sends a `SeverityNumber` but leaves `SeverityText` blank, Traceway computes the level:
+
+| Severity Number | Severity Text |
+| --------------- | ------------- |
+| 1-4 | TRACE |
+| 5-8 | DEBUG |
+| 9-12 | INFO |
+| 13-16 | WARN |
+| 17-20 | ERROR |
+| 21+ | FATAL |
+
+A severity number of `0` is treated as unset.
+
+## Linking Logs to Traces
+
+OTel Logs SDKs read the active span from the context you pass into `Emit` / `logger.log` / equivalent. When a log is emitted inside a request handler, background job, or child span, its `trace_id` and `span_id` are populated automatically — no plumbing on your side.
+
+In the Traceway dashboard, the trace detail page shows a **Logs** tab listing every log for that trace, plus an **All Distributed Traces** tab that pulls in logs from linked traces across services.
+
+## Example: Node.js
+
+```typescript
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
+import { BatchLogRecordProcessor } from "@opentelemetry/sdk-logs";
+import { Resource } from "@opentelemetry/resources";
+import { logs, SeverityNumber } from "@opentelemetry/api-logs";
+
+const sdk = new NodeSDK({
+ resource: new Resource({
+ "service.name": "my-service",
+ "service.version": "1.0.0",
+ }),
+ logRecordProcessors: [
+ new BatchLogRecordProcessor(
+ new OTLPLogExporter({
+ url: "https://your-traceway-instance.com/api/otel/v1/logs",
+ headers: {
+ Authorization: "Bearer your-project-token",
+ },
+ }),
+ ),
+ ],
+});
+
+sdk.start();
+
+const logger = logs.getLogger("app");
+
+logger.emit({
+ severityNumber: SeverityNumber.INFO,
+ severityText: "INFO",
+ body: "order received",
+ attributes: { "order.id": "ord_123" },
+});
+```
+
+When called inside an OTel-instrumented HTTP handler (or any code that runs under an active span), the emitted log automatically carries the active `trace_id` and `span_id`.
+
+## Example: Python
+
+```python
+import logging
+from opentelemetry import trace
+from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
+from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
+from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
+from opentelemetry.sdk.resources import Resource
+from opentelemetry._logs import set_logger_provider
+
+resource = Resource.create({
+ "service.name": "my-python-service",
+ "service.version": "1.0.0",
+})
+
+provider = LoggerProvider(resource=resource)
+set_logger_provider(provider)
+
+exporter = OTLPLogExporter(
+ endpoint="https://your-traceway-instance.com/api/otel/v1/logs",
+ headers={"Authorization": "Bearer your-project-token"},
+)
+provider.add_log_record_processor(BatchLogRecordProcessor(exporter))
+
+handler = LoggingHandler(level=logging.NOTSET, logger_provider=provider)
+logging.getLogger().addHandler(handler)
+logging.getLogger().setLevel(logging.INFO)
+
+logging.info("order received", extra={"order.id": "ord_123"})
+```
+
+The standard `LoggingHandler` bridges Python's `logging` module to OTel. Logs emitted inside a traced request automatically pick up the current trace and span IDs.
+
+## Example: Go
+
+```go
+import (
+ "context"
+ "time"
+
+ "go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttp"
+ otellog "go.opentelemetry.io/otel/log"
+ sdklog "go.opentelemetry.io/otel/sdk/log"
+ "go.opentelemetry.io/otel/sdk/resource"
+ semconv "go.opentelemetry.io/otel/semconv/v1.26.0"
+)
+
+func initLogs(ctx context.Context) (*sdklog.LoggerProvider, error) {
+ exporter, err := otlploghttp.New(ctx,
+ otlploghttp.WithEndpoint("your-traceway-instance.com"),
+ otlploghttp.WithURLPath("/api/otel/v1/logs"),
+ otlploghttp.WithHeaders(map[string]string{
+ "Authorization": "Bearer your-project-token",
+ }),
+ )
+ if err != nil {
+ return nil, err
+ }
+
+ res, _ := resource.New(ctx, resource.WithAttributes(
+ semconv.ServiceName("my-service"),
+ ))
+
+ lp := sdklog.NewLoggerProvider(
+ sdklog.WithProcessor(sdklog.NewBatchProcessor(exporter,
+ sdklog.WithExportInterval(2*time.Second))),
+ sdklog.WithResource(res),
+ )
+ return lp, nil
+}
+
+// Emit a log inside an active span context.
+func logInfo(ctx context.Context, logger otellog.Logger, msg string) {
+ rec := otellog.Record{}
+ rec.SetTimestamp(time.Now())
+ rec.SetSeverity(otellog.SeverityInfo)
+ rec.SetSeverityText("INFO")
+ rec.SetBody(otellog.StringValue(msg))
+ logger.Emit(ctx, rec)
+}
+```
+
+When `ctx` carries an active span (for example, the request context inside a Gin or net/http handler instrumented with OTel), the log automatically carries that span's trace and span IDs.
+
+## Quick Start: OTel Collector
+
+If you route telemetry through a Collector, add a `logs` pipeline that targets the same OTLP/HTTP endpoint:
+
+```yaml
+exporters:
+ otlphttp:
+ endpoint: "https://your-traceway-instance.com/api/otel"
+ headers:
+ Authorization: "Bearer your-project-token"
+
+service:
+ pipelines:
+ traces:
+ exporters: [otlphttp]
+ metrics:
+ exporters: [otlphttp]
+ logs:
+ exporters: [otlphttp]
+```
+
+## Next Steps
+
+- [Traces](/client/otel/traces) — how OTel spans map to Traceway concepts
+- [Metrics](/client/otel/metrics) — supported metric types and histogram handling
+- [Overview](/client/otel) — protocol details and authentication
diff --git a/docs/pages/client/symfony/_meta.json b/docs/pages/client/symfony/_meta.json
index 91ee60a7..0aa51d6b 100644
--- a/docs/pages/client/symfony/_meta.json
+++ b/docs/pages/client/symfony/_meta.json
@@ -3,5 +3,6 @@
"exceptions": "Exceptions",
"spans": "Spans",
"tasks": "Tasks",
- "metrics": "Metrics"
+ "metrics": "Metrics",
+ "logs": "Logs"
}
diff --git a/docs/pages/client/symfony/index.mdx b/docs/pages/client/symfony/index.mdx
index e3ee6e75..e3eba6c6 100644
--- a/docs/pages/client/symfony/index.mdx
+++ b/docs/pages/client/symfony/index.mdx
@@ -38,6 +38,7 @@ OTEL_PHP_AUTOLOAD_ENABLED=true
OTEL_SERVICE_NAME=my-symfony-app
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp
+OTEL_LOGS_EXPORTER=otlp
OTEL_EXPORTER_OTLP_PROTOCOL=http/json
OTEL_EXPORTER_OTLP_ENDPOINT=https://your-traceway-instance.com/api/otel
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-project-token"
@@ -124,4 +125,5 @@ Visit `/testing` in your browser, then check the Traceway dashboard — the exce
- [Spans](/client/symfony/spans) — create custom spans to measure sub-operations
- [Tasks](/client/symfony/tasks) — trace Symfony Messenger background jobs
- [Metrics](/client/symfony/metrics) — track custom counters, histograms, and gauges
-- [OpenTelemetry docs](/client/otel) — how OTel traces and metrics map to Traceway
+- [Logs](/client/symfony/logs) — forward Monolog / PSR-3 logs to Traceway
+- [OpenTelemetry docs](/client/otel) — how OTel traces, metrics, and logs map to Traceway
diff --git a/docs/pages/client/symfony/logs.mdx b/docs/pages/client/symfony/logs.mdx
new file mode 100644
index 00000000..ad818d2a
--- /dev/null
+++ b/docs/pages/client/symfony/logs.mdx
@@ -0,0 +1,161 @@
+# Logs
+
+Forward your Symfony application logs to Traceway via the OpenTelemetry Logs OTLP endpoint. The recommended path is a Monolog handler that bridges Symfony's standard PSR-3 logger to the OTel Logs SDK — all of your existing `$logger->info(...)` / `$logger->error(...)` calls keep working, and each log is automatically linked to the active trace and span.
+
+## Install the Logs Packages
+
+```bash
+composer require \
+ open-telemetry/opentelemetry-logger-monolog \
+ open-telemetry/sdk \
+ open-telemetry/exporter-otlp
+```
+
+- `opentelemetry-logger-monolog` — Monolog handler that emits records to the OTel Logs SDK.
+- `sdk` and `exporter-otlp` — already installed if you completed the [Quick Start](/client/symfony), listed here for completeness.
+
+## Configure Environment Variables
+
+Extend the env config from the Quick Start to also enable the logs exporter:
+
+```bash
+# Existing traces + metrics config from the Quick Start
+OTEL_PHP_AUTOLOAD_ENABLED=true
+OTEL_SERVICE_NAME=my-symfony-app
+OTEL_TRACES_EXPORTER=otlp
+OTEL_METRICS_EXPORTER=otlp
+
+# New: enable OTLP logs
+OTEL_LOGS_EXPORTER=otlp
+
+OTEL_EXPORTER_OTLP_PROTOCOL=http/json
+OTEL_EXPORTER_OTLP_ENDPOINT=https://your-traceway-instance.com/api/otel
+OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-project-token"
+```
+
+`OTEL_EXPORTER_OTLP_ENDPOINT` is the base URL — the logs exporter appends `/v1/logs` automatically. No extra endpoint config is needed.
+
+## Wire the Monolog Handler
+
+Register the OTel Monolog handler in `config/packages/monolog.yaml` so every channel (app, request, security, doctrine, …) is forwarded to Traceway:
+
+```yaml
+# config/packages/monolog.yaml
+monolog:
+ handlers:
+ traceway:
+ type: service
+ id: OpenTelemetry\Contrib\Logs\Monolog\Handler
+ level: info
+ channels: ~ # all channels
+
+services:
+ OpenTelemetry\Contrib\Logs\Monolog\Handler:
+ arguments:
+ $loggerProvider: '@OpenTelemetry\API\Logs\LoggerProviderInterface'
+ $level: !php/const Monolog\Logger::INFO
+ $bubble: true
+```
+
+The `$loggerProvider` argument is resolved by the OTel PHP autoloader — it's available as a service as soon as `OTEL_PHP_AUTOLOAD_ENABLED=true` is set.
+
+Set `level` to the Monolog level threshold you want forwarded. Use `debug` during early development to verify the pipeline, then raise it to `info` or `warning` in production to keep volume under control.
+
+## Emit Logs With Trace Context
+
+Inject Symfony's standard `Psr\Log\LoggerInterface` as usual — the Monolog handler takes care of bridging to OTel, and trace context attaches automatically:
+
+```php
+// src/Controller/OrderController.php
+namespace App\Controller;
+
+use Psr\Log\LoggerInterface;
+use Symfony\Component\HttpFoundation\JsonResponse;
+use Symfony\Component\HttpFoundation\Response;
+use Symfony\Component\Routing\Attribute\Route;
+
+class OrderController
+{
+ public function __construct(
+ private readonly LoggerInterface $logger,
+ ) {}
+
+ #[Route('/orders', methods: ['POST'])]
+ public function create(): Response
+ {
+ $this->logger->info('order received', ['order.id' => 'ord_123']);
+
+ try {
+ // ... business logic ...
+ $this->logger->info('order processed', ['order.id' => 'ord_123']);
+ return new JsonResponse(['status' => 'ok']);
+ } catch (\Throwable $e) {
+ $this->logger->error('order failed', [
+ 'order.id' => 'ord_123',
+ 'exception' => $e->getMessage(),
+ ]);
+ throw $e;
+ }
+ }
+}
+```
+
+Because the controller runs inside the OTel-instrumented request span, every log emitted here carries that span's `trace_id` and `span_id` automatically. Open the endpoint's trace in the Traceway dashboard and the **Logs** tab will show these records attached.
+
+The same is true for logs emitted inside Messenger handlers, Console commands, and any other code that runs under an active span.
+
+## Severity Mapping
+
+Monolog levels are mapped to OpenTelemetry severity numbers (and therefore Traceway's TRACE → FATAL labels) as follows:
+
+| Monolog Level | OTLP Severity Number | Traceway Severity |
+| ------------- | -------------------- | ----------------- |
+| `DEBUG` | 5 | DEBUG |
+| `INFO` | 9 | INFO |
+| `NOTICE` | 10 | INFO |
+| `WARNING` | 13 | WARN |
+| `ERROR` | 17 | ERROR |
+| `CRITICAL` | 18 | ERROR |
+| `ALERT` | 19 | ERROR |
+| `EMERGENCY` | 21 | FATAL |
+
+Only records at or above the handler's configured `level` threshold are forwarded.
+
+## Test Your Integration
+
+Add a route that logs at multiple levels, hit it once, and check the **Logs** page in the Traceway dashboard:
+
+```php
+// src/Controller/LogTestController.php
+namespace App\Controller;
+
+use Psr\Log\LoggerInterface;
+use Symfony\Component\HttpFoundation\JsonResponse;
+use Symfony\Component\HttpFoundation\Response;
+use Symfony\Component\Routing\Attribute\Route;
+
+class LogTestController
+{
+ public function __construct(
+ private readonly LoggerInterface $logger,
+ ) {}
+
+ #[Route('/log-test', name: 'log_test')]
+ public function test(): Response
+ {
+ $this->logger->debug('debug sample');
+ $this->logger->info('info sample', ['request.id' => 'req_1']);
+ $this->logger->warning('warning sample');
+ $this->logger->error('error sample', ['order.id' => 'ord_1']);
+ return new JsonResponse(['emitted' => 4]);
+ }
+}
+```
+
+Visit `/log-test`, then open **Logs** in the dashboard. You should see all four records within a few seconds, each linked to the trace for that request.
+
+## Next Steps
+
+- [Exceptions](/client/symfony/exceptions) — record caught exceptions with context
+- [Metrics](/client/symfony/metrics) — custom counters, histograms, and gauges
+- [OTel Logs reference](/client/otel/logs) — full OTLP logs mapping and severity details
diff --git a/docs/pages/learn/_meta.json b/docs/pages/learn/_meta.json
index dcc471c0..b7c5c453 100644
--- a/docs/pages/learn/_meta.json
+++ b/docs/pages/learn/_meta.json
@@ -7,6 +7,7 @@
"attributes": "Attributes",
"spans": "Spans",
"metrics": "Metrics",
+ "logs": "Logs",
"alerts": "Alerts",
"embedded-mode": "Embedded Mode",
"build-tags": "Build Tags",
diff --git a/docs/pages/learn/logs.mdx b/docs/pages/learn/logs.mdx
new file mode 100644
index 00000000..aa73eed9
--- /dev/null
+++ b/docs/pages/learn/logs.mdx
@@ -0,0 +1,80 @@
+# Logs
+
+Logs are time-stamped records emitted by your application as it runs. Traceway ingests OpenTelemetry logs via OTLP/HTTP, indexes them by body, severity, service, trace, and attributes, and links each log back to the trace and span that produced it.
+
+## Log Record Structure
+
+Each log record contains the following fields:
+
+| Field | Description |
+| --------------------- | ----------------------------------------------------------------------------------- |
+| Timestamp | When the log was emitted |
+| Severity Number | OTLP severity number (1-24) that maps to a text level |
+| Severity Text | `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, or `FATAL` |
+| Service Name | From the resource attribute `service.name` |
+| Body | The log message |
+| Trace ID | Hex-encoded OTel trace ID of the active span (if any) |
+| Span ID | Hex-encoded OTel span ID of the active span (if any) |
+| Resource Attributes | Key-value pairs from the resource (e.g. `service.version`, `deployment.environment`) |
+| Scope Attributes | Key-value pairs from the instrumentation scope |
+| Log Attributes | Key-value pairs attached to the log record itself |
+
+## Severity Levels
+
+Traceway supports six severity levels, matching the OpenTelemetry specification:
+
+| Severity | OTLP Number Range | Use Case |
+| -------- | ----------------- | ------------------------------------------------- |
+| TRACE | 1-4 | Very detailed diagnostic output |
+| DEBUG | 5-8 | Developer-level debug information |
+| INFO | 9-12 | Routine operational messages |
+| WARN | 13-16 | Unexpected but recoverable conditions |
+| ERROR | 17-20 | Errors that don't stop the service |
+| FATAL | 21+ | Errors that cause termination or severe impact |
+
+If your SDK sends only a severity number (no text), Traceway assigns the text level based on the number's range. If it sends only a text level, the number is computed from the text.
+
+## Attributes: Resource, Scope, Log
+
+OTel logs carry three layers of attributes, all of which are indexed and searchable in Traceway:
+
+- **Resource attributes** describe the emitting process — e.g. `service.name`, `service.version`, `host.name`, `deployment.environment`. Every log emitted by a given service carries the same resource attributes.
+- **Scope attributes** describe the instrumentation library or logger emitting the record — e.g. `logger.name`, scope `version`. Useful for separating framework logs from application logs.
+- **Log attributes** are specific to a single log record — e.g. `user.id`, `order.id`, `request.method`. These are the per-event details you add when logging.
+
+See [Attributes](/learn/attributes) for the general model used across traces, spans, and logs.
+
+## Searching Logs
+
+The **Logs** page supports filtering and search across all three attribute layers plus the body:
+
+- **Severity threshold** — keep only records at or above a minimum level (e.g. `WARN+` hides INFO and below).
+- **Service** — exact match on `service.name`.
+- **Trace** — exact match on the hex trace ID, or on a Traceway distributed trace ID (returns logs from every linked trace).
+- **Body search** — full-text search over the log message. Single-token queries use a token-bloom index for speed; multi-word or punctuation-heavy queries fall back to substring matching.
+- **Attribute filters** — exact match on any `resource.*`, `scope.*`, or log attribute key.
+- **Time range** — pick from presets (24h, 7d, 30d) or a custom window.
+
+All filters combine, and results paginate.
+
+## Linking to Traces
+
+When your SDK emits a log inside an active OTel span context, the log record automatically carries that span's `trace_id` and `span_id`. This means:
+
+- Every endpoint and task detail page has a **Logs** panel showing the log lines for that trace.
+- When a trace crosses service boundaries, a **Distributed Traces** tab shows logs from every service that participated.
+- Jumping from a log to the trace that produced it is a single click in the dashboard.
+
+No extra configuration is required — the standard OTel context propagation carries the IDs to your logger.
+
+## Retention
+
+Logs are stored in ClickHouse with daily partitioning and a 30-day TTL on the timestamp date. Older logs are removed automatically without operator intervention.
+
+## Sending Logs
+
+See the SDK-specific guides for setup instructions:
+
+- [OpenTelemetry](/client/otel/logs) — direct SDK export or OTel Collector
+- [Symfony](/client/symfony/logs) — Monolog handler and the OTel PHP Logs API
+- [Cloudflare Workers](/client/cloudflare) — Worker-side OTel logs exporter
diff --git a/website/app/product/logs/page.tsx b/website/app/product/logs/page.tsx
new file mode 100644
index 00000000..7f07fa9a
--- /dev/null
+++ b/website/app/product/logs/page.tsx
@@ -0,0 +1,175 @@
+import Image from "next/image";
+import Link from "next/link";
+
+import { Badge } from "@/components/ui/badge";
+import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from "@/components/ui/accordion";
+import { ArrowRight, ScrollText, Network, Boxes } from "lucide-react";
+
+export default function LogsPage() {
+ return (
+ <main className="min-h-screen bg-white text-zinc-950 font-sans selection:bg-zinc-100 selection:text-zinc-900">
+ {/* Hero Section */}
+ <section className="relative pt-16 pb-20 overflow-hidden">
+ <div className="absolute inset-0 -z-10 h-full w-full bg-white bg-[radial-gradient(#e5e7eb_1px,transparent_1px)] [background-size:16px_16px] [mask-image:radial-gradient(ellipse_50%_50%_at_50%_50%,#000_70%,transparent_100%)]"></div>
+ <div className="container mx-auto px-4 text-center">
+ <Badge variant="secondary" className="mb-4 bg-amber-50 text-amber-700 hover:bg-amber-100 px-2.5 py-0.5 border border-amber-100 text-xs font-normal rounded-full">
+ Logs
+ </Badge>
+ <h1 className="text-4xl md:text-6xl font-bold tracking-tight mb-6 text-zinc-900">
+ Every log, <br /> <span className="text-transparent bg-clip-text bg-gradient-to-r from-amber-500 to-orange-600">with its full trace attached</span>
+ </h1>
+ <p className="text-zinc-600 text-lg md:text-xl max-w-2xl mx-auto mb-10 leading-relaxed font-medium">
+ Stop jumping between a log viewer and a trace viewer. Search by severity, service, or attribute, then open the exact request that produced any log line in one click.
+ </p>
+ <div className="flex flex-col sm:flex-row items-center justify-center gap-3">
+ <Link href="https://docs.tracewayapp.com/learn/logs" className="inline-flex items-center justify-center gap-2 rounded-md text-sm font-medium transition-all cursor-pointer h-10 px-6 bg-zinc-900 text-white hover:bg-zinc-800 shadow-lg shadow-zinc-900/20">
+ Get Started <ArrowRight className="ml-2 h-4 w-4" />
+ </Link>
+ <Link href="http://cloud.tracewayapp.com/register" className="inline-flex items-center justify-center gap-2 rounded-md text-sm font-medium transition-all cursor-pointer h-10 px-6 border border-zinc-200 bg-white hover:bg-zinc-50 text-zinc-900 shadow-sm">
+ Try Traceway Cloud
+ </Link>
+ </div>
+ </div>
+ </section>
+
+ {/* Search Across Every Log Section */}
+ <section className="py-24 bg-white border-y border-zinc-100">
+ <div className="container mx-auto px-4 max-w-5xl">
+ <div className="flex flex-col md:flex-row items-center gap-12 lg:gap-20">
+ <div className="flex-1 space-y-6">
+ <div className="w-12 h-12 bg-amber-50 rounded-2xl flex items-center justify-center">
+ <ScrollText className="w-6 h-6 text-amber-600" />
+ </div>
+ <h2 className="text-2xl md:text-3xl font-bold text-zinc-900 tracking-tight">Search across every log</h2>
+ <p className="text-zinc-600 text-lg leading-relaxed">
+ Filter by severity, service, or trace. Full-text search over log bodies is powered by a token
+ index, and any resource, scope, or log attribute can be queried for exact matches.
+ </p>
+ <ul className="space-y-3 pt-2">
+ <li className="flex items-center gap-3 text-zinc-700">
+ <div className="w-1.5 h-1.5 rounded-full bg-amber-500"></div>
+ Body search backed by token indexes
+ </li>
+ <li className="flex items-center gap-3 text-zinc-700">
+ <div className="w-1.5 h-1.5 rounded-full bg-amber-500"></div>
+ Six severity levels: TRACE, DEBUG, INFO, WARN, ERROR, FATAL
+ </li>
+ <li className="flex items-center gap-3 text-zinc-700">
+ <div className="w-1.5 h-1.5 rounded-full bg-amber-500"></div>
+ Attribute filters on resource, scope, and log fields
+ </li>
+ </ul>
+ </div>
+ <div className="flex-1 w-full relative">
+ <div className="absolute inset-0 bg-gradient-to-tr from-amber-100/50 to-transparent rounded-3xl transform rotate-3 scale-105 -z-10"></div>
+ <div className="relative rounded-xl overflow-hidden border border-zinc-200 bg-white">
+ <Image
+ src="/images/logs.png"
+ alt="Logs search and detail view"
+ width={1200}
+ height={700}
+ className="w-full h-auto"
+ />
+ </div>
+ </div>
+ </div>
+ </div>
+ </section>
+
+ {/* Linked to Traces + OpenTelemetry Native (2-card grid) */}
+ <section className="py-24 bg-zinc-50/50">
+ <div className="container mx-auto px-4 max-w-5xl">
+ <div className="grid grid-cols-1 md:grid-cols-2 gap-8">
+ <div className="rounded-2xl border border-zinc-200 bg-white p-8 space-y-5">
+ <div className="w-12 h-12 bg-orange-50 rounded-2xl flex items-center justify-center">
+ <Network className="w-6 h-6 text-orange-600" />
+ </div>
+ <h2 className="text-xl md:text-2xl font-bold text-zinc-900 tracking-tight">Linked to every trace</h2>
+ <p className="text-zinc-600 leading-relaxed">
+ Every log carries the trace and span ID of the request that emitted it. Open any
+ endpoint and see the exact log lines tied to that invocation &mdash; or follow a distributed trace
+ to see logs from every service it touched.
+ </p>
+ <ul className="space-y-3 pt-1">
+ <li className="flex items-center gap-3 text-zinc-700">
+ <div className="w-1.5 h-1.5 rounded-full bg-orange-500"></div>
+ Trace and span context on every log
+ </li>
+ <li className="flex items-center gap-3 text-zinc-700">
+ <div className="w-1.5 h-1.5 rounded-full bg-orange-500"></div>
+ Per-trace and per-distributed-trace views
+ </li>
+ <li className="flex items-center gap-3 text-zinc-700">
+ <div className="w-1.5 h-1.5 rounded-full bg-orange-500"></div>
+ Jump from a log to the span that produced it
+ </li>
+ </ul>
+ </div>
+
+ <div className="rounded-2xl border border-zinc-200 bg-white p-8 space-y-5">
+ <div className="w-12 h-12 bg-green-50 rounded-2xl flex items-center justify-center">
+ <Boxes className="w-6 h-6 text-green-600" />
+ </div>
+ <h2 className="text-xl md:text-2xl font-bold text-zinc-900 tracking-tight">OpenTelemetry-native</h2>
+ <p className="text-zinc-600 leading-relaxed">
+ Send logs from any OTel SDK &mdash; Node.js, Python, Go, Java, .NET, PHP. No vendor client needed.
+ OTLP/HTTP ingestion supports both Protobuf and JSON, and data is stored with a 30-day TTL.
+ </p>
+ <ul className="space-y-3 pt-1">
+ <li className="flex items-center gap-3 text-zinc-700">
+ <div className="w-1.5 h-1.5 rounded-full bg-green-500"></div>
+ Standard OTLP endpoint at /api/otel/v1/logs
+ </li>
+ <li className="flex items-center gap-3 text-zinc-700">
+ <div className="w-1.5 h-1.5 rounded-full bg-green-500"></div>
+ Works with the OTel Collector or direct SDK export
+ </li>
+ <li className="flex items-center gap-3 text-zinc-700">
+ <div className="w-1.5 h-1.5 rounded-full bg-green-500"></div>
+ 30-day retention, fully indexed
+ </li>
+ </ul>
+ </div>
+ </div>
+ </div>
+ </section>
+
+ {/* FAQ Section */}
+ <section className="py-24 bg-zinc-50 border-t border-zinc-100">
+ <div className="container mx-auto px-4 max-w-3xl">
+ <div className="text-center mb-12">
+ <h2 className="text-3xl font-bold mb-4 text-zinc-900 tracking-tight">Frequently Asked Questions</h2>
+ <p className="text-zinc-600 text-lg">
+ Common questions about logs with Traceway.
+ </p>
+ </div>
+
+ <Accordion type="single" collapsible className="w-full">
+ <AccordionItem value="item-1" className="border-b-zinc-200">
+ <AccordionTrigger className="text-zinc-900 hover:text-zinc-700 hover:no-underline text-left">
+ How do I send logs to Traceway?
+ </AccordionTrigger>
+ <AccordionContent className="text-zinc-600 leading-relaxed">
+ Point any OpenTelemetry Logs SDK at <code>/api/otel/v1/logs</code> with an
+ {" "}<code>Authorization: Bearer &lt;project_token&gt;</code> header. Protobuf and JSON are
+ both supported. If you already run an OTel Collector, route its <code>logs</code> pipeline to
+ the same endpoint.
+ </AccordionContent>
+ </AccordionItem>
+ <AccordionItem value="item-2" className="border-b-zinc-200">
+ <AccordionTrigger className="text-zinc-900 hover:text-zinc-700 hover:no-underline text-left">
+ Are logs linked to my traces automatically?
+ </AccordionTrigger>
+ <AccordionContent className="text-zinc-600 leading-relaxed">
+ Yes. Every log carries the OTel <code>trace_id</code> and <code>span_id</code> from the
+ active context at emission time. That means logs emitted inside a request handler, background
+ job, or child span are automatically associated with the corresponding trace &mdash; no extra
+ plumbing required.
+ </AccordionContent>
+ </AccordionItem>
+ </Accordion>
+ </div>
+ </section>
+ </main>
+ );
+}
diff --git a/website/components/mobile-nav.tsx b/website/components/mobile-nav.tsx
index 801031a4..ca9e6646 100644
--- a/website/components/mobile-nav.tsx
+++ b/website/components/mobile-nav.tsx
@@ -80,6 +80,13 @@ export function MobileNav() {
>
AI Tracing
</Link>
+ <Link
+ href="/product/logs"
+ className="text-lg font-medium text-zinc-600 hover:text-zinc-900 transition-colors pl-2"
+ onClick={() => setIsOpen(false)}
+ >
+ Logs
+ </Link>
<div className="border-t border-zinc-100"></div>
<Link
href="/cloud"
diff --git a/website/components/site-header.tsx b/website/components/site-header.tsx
index ca60f2a5..e98fed32 100644
--- a/website/components/site-header.tsx
+++ b/website/components/site-header.tsx
@@ -4,7 +4,7 @@ import { useState, useRef, useEffect } from "react";
import Link from "next/link";
import Image from "next/image";
-import { Github, AlertCircle, Activity, Video, ChevronDown, Network, Workflow } from "lucide-react";
+import { Github, AlertCircle, Activity, Video, ChevronDown, Network, Workflow, ScrollText } from "lucide-react";
import { MobileNav } from "@/components/mobile-nav";
export function SiteHeader() {
@@ -118,6 +118,19 @@ export function SiteHeader() {
<p className="text-xs text-zinc-500 mt-0.5">Monitor LLM costs, tokens, latency, and conversations</p>
</div>
</Link>
+ <Link
+ href="/product/logs"
+ className="flex items-start gap-3 rounded-md p-3 hover:bg-zinc-50 transition-colors"
+ onClick={() => setOpen(false)}
+ >
+ <div className="w-8 h-8 bg-amber-50 rounded-lg flex items-center justify-center shrink-0 mt-0.5">
+ <ScrollText className="w-4 h-4 text-amber-600" />
+ </div>
+ <div>
+ <div className="text-sm font-medium text-zinc-900">Logs</div>
+ <p className="text-xs text-zinc-500 mt-0.5">Search every log, linked to the trace that emitted it</p>
+ </div>
+ </Link>
</div>
)}
</div>
diff --git a/website/public/images/logs.png b/website/public/images/logs.png
new file mode 100644
index 00000000..f8cb3715
Binary files /dev/null and b/website/public/images/logs.png differ