Telemetry pipeline

Exporters, samplers, batching, and where data goes.

@sedata-ai/mcp runs an OpenTelemetry NodeSDK inside your process and exports data over OTLP. This page covers the moving parts.

Exporters

The exporter type is controlled by config.exporterType:

Value	Default?	Behavior
otlp-http	✅	Sends traces to <endpoint>/traces and metrics to <endpoint>/metrics.
otlp-grpc		gRPC trace exporter (metrics still HTTP).
console		ConsoleSpanExporter writes spans to stdout. No metric reader is attached.

Endpoint composition:

exporterEndpoint = "https://otel.sedata-ai.tech/v1"
                       ↓
trace exporter URL  → https://otel.sedata-ai.tech/v1/traces
metric exporter URL → https://otel.sedata-ai.tech/v1/metrics

A trailing slash is normalized — both https://host/v1 and https://host/v1/ work.

Authentication headers

exporterAuth is converted to HTTP headers and applied to both the trace and metric exporters:

type	Header(s) sent
bearer	Authorization: Bearer <token>
apiKey	x-api-key: <apiKey>
basic	Currently disabled in the exporter (validated but not sent)

basic auth is permitted by ConfigValidator but the actual header is commented out in the OTLP setup. Use bearer or apiKey until that ships.

Sampling

const config: TelemetryConfig = {
  samplingRate: 1.0, // default: keep everything
}

The sampler is TraceIdRatioBasedSampler — deterministic by trace id, head-based. Out-of-range values throw on validation.

Value	Effect
1.0	All traces recorded.
0.1	~10% of traces recorded.
0	No traces.

Metrics are not sampled — enableMetrics is the only switch for metrics.

Batching

Trace exporter batching is delegated to OTel’s standard BatchSpanProcessor defaults.

The metric reader is a PeriodicExportingMetricReader with two knobs:

Option	Default	Purpose
metricExportIntervalMs	5000	How often to flush metrics.
batchTimeoutMs	2000	Per-batch export timeout.

Resource detection

The SDK runs these resource detectors at startup:

• envDetector — picks up OTEL_RESOURCE_ATTRIBUTES.
• hostDetector — host name + arch.
• osDetector — OS name + version.
• serviceInstanceIdDetectorSync — generates a stable service.instance.id.

Plus the package adds:

• service.name from config.serverName
• service.version from config.serverVersion
• mcp.session.id (per-process UUID)

Toggles

Every part of the pipeline is opt-out:

Flag	Default	Effect
enableTracing	true	Set false to skip the trace exporter and sampler.
enableMetrics	true	Set false to skip the metric reader.
enableArgumentCollection	false	Add tool args to span attributes.
enablePIISanitization	true	Reserved — used by the data-processor pipeline.

Custom data processors

You can mutate every attribute set right before export:

const config: TelemetryConfig = {
  // ...
  dataProcessors: [
    (data) => {
      // remove anything matching a pattern
      const cleaned = { ...data }
      delete cleaned['mcp.request.argument.api_key']
      return cleaned
    },
  ],
}

Processors run in order and receive the merged attribute object (always includes mcp.session.id). See Data processors.

Shutdown

Always call shutdown on graceful exit so in-flight metrics flush:

process.on('SIGTERM', async () => {
  await telemetry.shutdown()
  process.exit(0)
})

shutdown() records mcp.server.session.duration and then calls NodeSDK.shutdown(), which flushes both the trace exporter and metric reader.

Next

Authentication

All three auth shapes with examples.

Sampling

Choosing a rate that survives production.