OpenTelemetry configuration

Telemetry is configured from three places. Higher rows win:

Telemetry stays off until a destination exists in one of them. With no destination, Elide starts no telemetry threads, opens no connections, and the OpenTelemetry APIs in your code do nothing.

When each source is read

A one-shot run looks for the word opentelemetry in the project’s elide.pkl before evaluating it, so a block inherited from another module is not seen by elide run file.ts; projects without telemetry pay nothing.

The elide.pkl block

amends "elide:project.pkl"

name = "checkout"

opentelemetry {
  service { name = "checkout"; version = "1.4.2"; environment = "production" }
  resource { ["cloud.region"] = "us-east-1" }

  destinations {
    ["collector"] { endpoint = "http://localhost:4317"; protocol = "grpc" }
    ["sentry"] { provider = "sentry" }
  }

  traces { sampler = "parentbased_traceidratio"; ratio = 0.25 }
  metrics { interval = 30.s }
  logs { level = "info" }
  runtime { logs = "warn" }
}

Credentials never go in elide.pkl. A destination names the environment variable that holds them (credential, dsn, headerEnv), and Elide reads it at startup.

Top level

Signals

Destinations

Each entry in destinations is one place telemetry goes. The name is yours; it appears in error messages.

Several destinations can be active at once. Each receives only the signals it lists, or that its provider takes by default:

opentelemetry {
  destinations {
    ["collector"] { endpoint = "http://otel-collector:4318" }
    ["errors"] { provider = "sentry" }
    ["metrics"] { provider = "datadog"; site = "us5"; signals { "metrics" } }
  }
}

A collector that needs a token:

opentelemetry {
  destinations {
    ["collector"] {
      endpoint = "https://otel.example.com"
      headerEnv { ["authorization"] = "OTEL_COLLECTOR_AUTH" }
      perSignal { ["metrics"] { endpoint = "https://metrics.example.com/otlp/v1/metrics" } }
    }
  }
}

The complete schema, with every other elide.pkl block, is in the elide.pkl reference.

Environment variables

Elide reads the standard OpenTelemetry SDK variables. An invalid value is ignored, and the setting keeps its manifest or default value.

Elide adds shorthands for providers and for settings the standard variables do not cover:

OTEL_EXPORTER_OTLP_* apply to every destination that uses the otlp provider, including ones named in elide.pkl. Provider credentials come from the variables listed on Providers.

Flags

The flags take = and apply to run, serve, test, build, and install:

elide run --otel-endpoint=http://localhost:4317 --otel-protocol=grpc app.ts
elide test --no-otel

At exit

When a program ends, Elide still holds telemetry it has not sent: the last log records and spans, and a final collection of metrics. The shutdown mode decides how that leaves the process:

sidecar is the default on Linux and macOS. The exporter is a small elide process, one per user, started by the first exit that needs it. It accepts requests only from processes of the same user, keeps them in memory only, sends each one once with the usual retries, and exits once no Elide process of that user is left and its queue is sent or has expired. It never runs longer than 15 minutes. If the exporter cannot be started or reached in time, the final export is dropped and counted, never sent from the exiting process.

On Windows, inline is the only mode; sidecar falls back to it with a warning. Choose inline to have the exiting process send the data itself, for example when nothing may outlive the program:

elide run --otel-shutdown=inline app.ts
ELIDE_OTEL_SHUTDOWN=drop elide run app.ts

How sources combine

• Destinations merge by name. A destination from --otel-provider=honeycomb and one named honeycomb in elide.pkl are the same destination; the flag’s fields win.
• OTEL_EXPORTER_OTLP_* settings apply to every otlp destination. With no otlp destination, an endpoint variable creates one named otlp.
• elide.pkl and flag values are checked strictly: a bad value leaves telemetry off for the run, with a warning; see Configuration errors. Bad variable values are skipped.
• A destination left with no enabled signal is skipped. When no destination receives anything, telemetry stays off.
• Configuration is read once, at startup. Your code cannot change destinations, headers, or the resource.

Samples

• OTLP to a local collector