@seda-protocol/telemetry

Effect-based OpenTelemetry integration. Wraps any Effect program with OTLP trace export and optional metrics (Prometheus scrape or OTLP push), including Effect fiber metrics, Node.js runtime metrics, and host metrics.

Usage

import { ProvideTelemetry } from "@seda-protocol/telemetry";

program.pipe(
  ProvideTelemetry("my-service", "1.0.0", {
    resourceAttributes: { environment: "production" },
  }),
);

Options

| Option | Description | Default | |---|---|---| | resourceAttributes | Attributes added to the OpenTelemetry resource. | {} | | registerGlobalTracer | Register the trace provider globally for third-party OTEL libraries. | true | | shutdownTimeout | Timeout when shutting down telemetry on exit. | 3000 ms |

Configuration

Telemetry is disabled when OTLP_ENDPOINT is unset and no metrics export mode is active.

OTLP collector base URL

OTLP_ENDPOINT should be the collector base URL (for example http://localhost:4318). Traces are sent to <base> + OTLP_TRACES_PATH_SUFFIX and OTLP metrics to <base> + OTLP_METRICS_PATH_SUFFIX (defaults /v1/traces and /v1/metrics).

If the endpoint ends with /v1/traces (as was common in prior versions), it is normalized to the base URL and a warning is logged.

Tracing

| Variable | Description | Default | |---|---|---| | OTLP_ENDPOINT | Collector base URL for OTLP export. Disabled when unset or empty. | (disabled) | | OTLP_TRACES_PATH_SUFFIX | Path appended to the base URL for trace export. Set to empty to use the base URL as-is. | /v1/traces | | OTLP_SAMPLING_RATIO | Fraction of traces to sample (0–1). | 0.1 |

Metrics export modes

Choose how metrics are exported with METRICS_EXPORTER:

| Mode | METRICS_EXPORTER | Required variables | |---|---|---| | Prometheus scrape (default when PROMETHEUS_PORT is set) | prometheus or unset | PROMETHEUS_PORT | | OTLP push | otlp | OTLP_ENDPOINT (base URL) |

OTLP push exports OpenTelemetry metrics (not Prometheus text format). A collector can forward them to Prometheus or other backends.

| Variable | Description | Default | |---|---|---| | METRICS_EXPORTER | prometheus or otlp. When unset and PROMETHEUS_PORT is set, defaults to Prometheus scrape. | (unset) | | OTLP_METRICS_PATH_SUFFIX | Path appended to the base URL for OTLP metrics export. Set to empty to use the base URL as-is. | /v1/metrics | | PROMETHEUS_PORT | Port for the /metrics scrape endpoint on http://localhost:<port>/metrics. | (disabled) | | OTLP_METRICS_EXPORT_INTERVAL_MS | Push interval for OTLP metrics. | 10000 | | NODE_MONITORING_PRECISION_MS | Node.js runtime metric collection interval in milliseconds. For Prometheus scrape, should be lower than the scrape interval. | 10 | | HOST_METRICS_GROUPS | Comma-separated host metric groups to collect. Supported values: system.cpu, system.memory, system.network, process.cpu, process.memory. When unset, all groups are collected. | (all) |

METRICS_EXPORTER=otlp cannot be combined with PROMETHEUS_PORT.