> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirador.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Logs over OTLP

> Export structured OpenTelemetry logs and correlate them with traces in Mirador

Mirador accepts structured OTLP log records over HTTP and gRPC. Logs appear live in your project's Logs view, where you can search message bodies, filter by severity or attributes, inspect patterns, and jump to correlated traces.

## Export logs

Configure any standard OTLP/HTTP log exporter:

```bash theme={null}
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://otel.mirador.org/v1/logs
export OTEL_EXPORTER_OTLP_LOGS_HEADERS=Authorization=mir_srv_xxx
```

For OTLP/gRPC, use the shared endpoint and protocol:

```bash theme={null}
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.mirador.org:4317
export OTEL_EXPORTER_OTLP_HEADERS=Authorization=mir_srv_xxx
```

Your logging framework needs an OpenTelemetry bridge or appender to turn native log entries into OTel `LogRecord` values. Language-specific OTel distributions often configure this automatically.

## Use a Collector

A Collector is useful when applications already write to stdout or use a logging backend. Add a receiver that matches your environment and export the resulting OTel logs to Mirador:

```yaml theme={null}
receivers:
  otlp:
    protocols:
      grpc:
      http:

exporters:
  otlp/mirador:
    endpoint: otel.mirador.org:4317
    headers:
      Authorization: ${env:MIRADOR_API_KEY}

service:
  pipelines:
    logs:
      receivers: [otlp]
      exporters: [otlp/mirador]
```

## Preserved fields

| OTLP field            | Mirador behavior                                                     |
| --------------------- | -------------------------------------------------------------------- |
| Timestamp             | Uses `time_unix_nano`, then observed time, then gateway receive time |
| Severity              | Preserves both severity number and severity text                     |
| Body                  | Stored as text; structured values are stringified                    |
| Log attributes        | Preserved as searchable key/value fields                             |
| Resource attributes   | Preserved, including `service.name`                                  |
| Instrumentation scope | Preserves scope name and version                                     |
| Trace ID and span ID  | Preserved as hexadecimal IDs for correlation                         |
| Event name and flags  | Preserved                                                            |

Arrays and key-value bodies or attributes are JSON encoded rather than discarded.

## Trace correlation

Logs carrying a valid `trace_id` and `span_id` are linked to the same trace and span in Mirador. Emit the log while a span is active and use your language's OTel logging integration so the current context is injected automatically.

<Tip>
  If logs arrive but are not correlated, inspect an exported record and confirm that both trace and span IDs are populated. An uncorrelated log is still stored and searchable.
</Tip>

## Delivery behavior

* Requests may use protobuf or JSON and may be gzip compressed.
* Oversized individual records are rejected and counted in the standard OTLP `ExportLogsPartialSuccess` response.
* Valid records in the same export continue when another record is rejected.
* A temporary publish failure returns an OTLP error so the exporter can retry.
* Data retention follows the policy configured for your Mirador plan.

## Next steps

<CardGroup cols={2}>
  <Card title="Traces over OTLP" icon="route" href="/opentelemetry/traces">
    Export spans and preserve trace IDs for correlation
  </Card>

  <Card title="Metrics over OTLP" icon="chart-line" href="/opentelemetry/metrics">
    Build live dashboards from OTel metrics
  </Card>
</CardGroup>