Any OpenTelemetry SDK

Monocle ingests standard OpenTelemetry data. If there is no Monocle SDK for your stack, point any OpenTelemetry SDK, or an OpenTelemetry Collector, at Monocle's OTLP endpoint.

Endpoint

Setting	Value
Protocol	OTLP over HTTP, `http/protobuf` (recommended) or `http/json`. gRPC is not supported.
Base URL	`https://ingest.monocle.sh`
Paths	`/v1/traces`, `/v1/logs`, `/v1/metrics`
Compression	`gzip` recommended
Body size	10 MB maximum per request

Authentication

Every request needs three headers. The first and the last come from your service's DSN:

https://mk_live_xxxxxxxx@ingest.monocle.sh/00000000-0000-4000-8000-000000000001
        └─ x-api-key ──┘                    └───────── x-monocle-service-id ─────────┘

Header	Value
`x-api-key`	The key of the DSN, starting with `mk_live_`
`x-monocle-service-id`	The service ID at the end of the DSN
`x-monocle-env`	The environment to report to: `production`, `staging`, or `development`

Configuration

Most OpenTelemetry SDKs read their exporter configuration from these standard environment variables:

.env

OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.monocle.sh
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_COMPRESSION=gzip
OTEL_EXPORTER_OTLP_HEADERS=x-api-key=mk_live_xxxxxxxx,x-monocle-service-id=00000000-0000-4000-8000-000000000001,x-monocle-env=production
OTEL_SERVICE_NAME=api
OTEL_RESOURCE_ATTRIBUTES=service.version=1.4.0,vcs.ref.head.revision=a1b2c3d4e5f60718293a4b5c6d7e8f9012345678

With an OpenTelemetry Collector, add an otlphttp exporter:

otel-collector.yaml

exporters:
  otlphttp/monocle:
    endpoint: https://ingest.monocle.sh
    compression: gzip
    headers:
      x-api-key: mk_live_xxxxxxxx
      x-monocle-service-id: 00000000-0000-4000-8000-000000000001
      x-monocle-env: production

How Monocle reads your data

Service: data is always filed under the DSN's service. The service.name you send is replaced with that service's name.
Environment: comes from the x-monocle-env header only. deployment.environment.name is not used for routing.
Release: Monocle records a deployment when a new service.version shows up on your entry spans. Set it to the release or commit you deploy, not to a placeholder such as 1.0.0. Add vcs.ref.head.revision with the commit SHA when the version is a semver tag.

To make your data show up in the specialized dashboards (Requests, Queries, Jobs…), follow the semantic conventions. Official OpenTelemetry instrumentations already do for most libraries.

Trace across services

When one service calls another, Monocle shows both in one trace, with the called service nested under the call. See Traces across services. Two things make it work:

Propagate the trace context. The caller sends the W3C traceparent header, and the called service continues the trace from it. W3C trace context is the default propagator of the OpenTelemetry SDKs, and the HTTP client and server instrumentations apply it for you. Keep it if you configure other propagators.
Send span flags. OTLP span flags tell Monocle whether the parent of a span ran in another process. Monocle uses them to find where each service starts in a trace. The OpenTelemetry JavaScript exporters send them from version 0.206.0. Without the flags, Monocle relies on the span kind, and still finds most HTTP requests and jobs.

Without the trace context, each service starts its own trace. Cross-service nesting, related exceptions, and the Internal badge of External Calls need it.

Errors

Monocle answers 401 Unauthorized without details when it rejects a request. Check the key, the service ID, and that x-monocle-env is one of your environments. Connection checks are cached for up to five minutes, so a fix can take a few minutes to apply. See Troubleshooting.