> ## 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.

# OpenTelemetry Overview

> Send traces, metrics, and logs to Mirador with the standard OTLP protocol

Mirador is an **OTLP-native observability platform**. Point an existing OpenTelemetry SDK or Collector at Mirador to ingest traces, metrics, and logs without replacing your instrumentation or adding a Mirador SDK.

| Signal      | Support                                                                      |
| ----------- | ---------------------------------------------------------------------------- |
| **Traces**  | OTLP spans, span events, status, attributes, and resource attributes         |
| **Metrics** | Gauge, Sum, Histogram, ExponentialHistogram, and Summary datapoints          |
| **Logs**    | Structured log records with severity, attributes, and trace/span correlation |

All three signals use the same endpoint and authentication. Data is isolated to the project that owns the API key.

## Endpoints

Mirador accepts OTLP over HTTP and gRPC in production and development:

| Transport | Production                             | Development                                |
| --------- | -------------------------------------- | ------------------------------------------ |
| OTLP/HTTP | `https://otel.mirador.org/v1/{signal}` | `https://otel-dev.mirador.org/v1/{signal}` |
| OTLP/gRPC | `otel.mirador.org:4317`                | `otel-dev.mirador.org:4317`                |

For OTLP/HTTP, replace `{signal}` with `traces`, `metrics`, or `logs`. The gateway accepts `application/x-protobuf` and `application/json`, with optional gzip compression.

<Note>
  When `OTEL_EXPORTER_OTLP_ENDPOINT` is set to `https://otel.mirador.org`, standards-compliant HTTP exporters append `/v1/traces`, `/v1/metrics`, or `/v1/logs` automatically. Signal-specific endpoint variables must include the full path.
</Note>

## Authentication

Send a Mirador API key in the standard OTLP `Authorization` header:

```bash theme={null}
OTEL_EXPORTER_OTLP_HEADERS=Authorization=mir_srv_xxx
```

Both key types are accepted:

* **Server keys** (`mir_srv_*`) are intended for backend services and Collectors.
* **Web keys** (`mir_web_*`) are intended for browsers and are validated against the key's allowed origins.

The canonical `Bearer` form is also accepted. In environment variables, URL-encode the space:

```bash theme={null}
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20mir_srv_xxx
```

Create or rotate keys from your project's API keys page in the Mirador dashboard.

## Configure an existing SDK

For OTLP/HTTP with protobuf:

```bash theme={null}
export OTEL_SERVICE_NAME=checkout-api
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.mirador.org
export OTEL_EXPORTER_OTLP_HEADERS=Authorization=mir_srv_xxx
```

For OTLP/gRPC:

```bash theme={null}
export OTEL_SERVICE_NAME=checkout-api
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 language's OpenTelemetry autoinstrumentation or SDK reads these standard variables. Restart the instrumented service after applying them.

## Use an OpenTelemetry Collector

Add Mirador as an exporter and send one or more pipelines to it:

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

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

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

If a pipeline already has another exporter, keep it and append `otlp/mirador` to fan out the same telemetry to both destinations.

## OTLP or the Mirador SDK?

Both feed Mirador's trace pipeline, so you can choose per service:

* Use **OpenTelemetry** for vendor-neutral instrumentation, existing OTel deployments, logs, and metrics.
* Use the **Mirador SDK** (`@miradorlabs/web-sdk` or `@miradorlabs/nodejs-sdk`) for typed web3 APIs, provider integration, and browser-specific features.

OTel applications can still trigger Mirador's external-system enrichment by adding reserved span events. See [Enrichment hints](/opentelemetry/enrichment-hints).

## Machine-readable contract

The live gateway publishes its canonical, agent-friendly integration contract at [`otel.mirador.org/llms.txt`](https://otel.mirador.org/llms.txt). It contains the exact enrichment event names, required attributes, endpoint rules, and complete examples.

## Next steps

<CardGroup cols={2}>
  <Card title="Traces" icon="route" href="/opentelemetry/traces">
    Export spans, events, attributes, and status
  </Card>

  <Card title="Metrics" icon="chart-line" href="/opentelemetry/metrics">
    Export counters, gauges, and distributions
  </Card>

  <Card title="Logs" icon="rectangle-list" href="/opentelemetry/logs">
    Export structured logs and correlate them with traces
  </Card>

  <Card title="Enrichment hints" icon="wand-magic-sparkles" href="/opentelemetry/enrichment-hints">
    Track onchain and external actions from OTel spans
  </Card>
</CardGroup>