TelemetryConfig

The single configuration object for the entire telemetry pipeline.

interface TelemetryConfig {
  serverName: string
  serverVersion: string
  exporterEndpoint?: string
  exporterType?: 'otlp-http' | 'otlp-grpc' | 'console'
  exporterAuth?: AuthConfig
  samplingRate?: number
  metricExportIntervalMs?: number
  batchTimeoutMs?: number
  enableMetrics?: boolean
  enableTracing?: boolean
  enablePIISanitization?: boolean
  enableArgumentCollection?: boolean
  dataProcessors?: ((data: any) => any)[]
}

Required fields

serverName · string · required

Maps to the OpenTelemetry service.name resource attribute. Use a stable, human-readable identifier for your service (weather-mcp, not dev-1).

serverVersion · string · required

Maps to service.version. Recommended: a release tag or git SHA.

Exporter

exporterEndpoint · string

Base OTLP endpoint, e.g. https://otel.sedata-ai.tech/v1. Required unless exporterType: 'console'. The package appends /traces and /metrics to derive the per-signal URLs.

exporterType · 'otlp-http' | 'otlp-grpc' | 'console' · default: "otlp-http"

Which exporter to use.

• otlp-http — OTLP/HTTP for traces and metrics (default).
• otlp-grpc — OTLP/gRPC trace exporter (metrics still HTTP).
• console — Print spans to stdout. No metric reader is attached.

exporterAuth · AuthConfig

Auth for the exporter. See AuthConfig. Also used to authenticate the safety-check API.

Sampling & batching

samplingRate · number · default: "1.0"

Trace sampling ratio in [0, 1]. Uses TraceIdRatioBasedSampler — deterministic by trace id.

metricExportIntervalMs · number · default: "5000"

Metric flush interval in milliseconds.

batchTimeoutMs · number · default: "2000"

Per-batch metric export timeout in milliseconds.

Toggles

enableTracing · boolean · default: "true"

Set false to skip the trace exporter and sampler.

enableMetrics · boolean · default: "true"

Set false to skip the metric reader.

enablePIISanitization · boolean · default: "true"

Reserved for built-in sanitization patterns. Pair with dataProcessors for active redaction today.

enableArgumentCollection · boolean · default: "false"

When true, every tool argument is flattened into mcp.request.argument.<key> span attributes. Off by default to avoid inadvertent PII leakage.

Custom processing

dataProcessors · ((data: any) => any)[]

Array of pure functions run on every attribute set before export. Run in order. See Data processors for patterns.

Defaults

const DEFAULT_CONFIG: Partial<TelemetryConfig> = {
  samplingRate: 1.0,
  metricExportIntervalMs: 5000,
  enablePIISanitization: true,
  enableArgumentCollection: false,
  exporterType: 'otlp-http',
  enableMetrics: true,
  enableTracing: true,
  batchTimeoutMs: 2000,
  dataProcessors: [],
}

Example

import type { TelemetryConfig } from '@sedata-ai/mcp'

const config: TelemetryConfig = {
  serverName: 'weather-mcp',
  serverVersion: process.env.GIT_SHA ?? '0.0.0-dev',
  exporterEndpoint: 'https://otel.sedata-ai.tech/v1',
  exporterAuth: {
    type: 'bearer',
    token: process.env.SEDATA_TOKEN!,
  },
  samplingRate: 0.25,
  metricExportIntervalMs: 10_000,
  enableArgumentCollection: false,
  dataProcessors: [
    (data) => ({ ...data, 'deployment.env': process.env.DEPLOY_ENV ?? 'dev' }),
  ],
}

Validation

ConfigValidator.validate(config) enforces the rules above. See the validator reference for the exact error messages.