Skip to main content
Hyperterse integrates with OpenTelemetry for distributed tracing and metrics. The observability subsystem instruments the execution pipeline, connector lifecycle, and MCP transport. Structured logging provides operational visibility at every level.

​
Tracing

When enabled, the runtime creates spans for each stage of tool execution:
SpanAttributes
MCP request handlingMethod, tool name, request ID
Auth plugin executionPlugin name, tool name, success/failure
Input transformTool name, script path
Connector executionAdapter name, connector type, cache hit/miss
Output transformTool name, script path
Connector initializationAdapter name, connector type
Traces follow the OpenTelemetry specification and export to any compatible backend: Jaeger, Zipkin, Grafana Tempo, Datadog, AWS X-Ray (via ADOT collector), or any OTLP receiver.

​
Metrics

MetricTypeDescription
Tool invocation countCountertools/call requests per tool
Execution durationHistogramEnd-to-end time per tool
Cache hit/miss ratioCounterHits vs. misses per query
Connector execution timeHistogramTime in connector Execute calls
Auth failure countCounterRejections per plugin
Metrics export through the configured OpenTelemetry meter provider.

​
Structured logging

Hyperterse uses a tagged structured logger with the following fields:
  • Timestamp — ISO 8601.
  • Level — ERROR (1), WARN (2), INFO (3), DEBUG (4).
  • Tag — Component identifier: runtime, executor, connector, mcp, auth.
  • Message — Descriptive text.
  • Fields — Structured key-value pairs (tool name, adapter, duration, error details).

​
Log levels

LevelValueDescription
Error1Unrecoverable failures. Connector init failures, fatal config errors.
Warn2Recoverable issues. Cache misses on expected hits, slow queries.
Info3Operational events. Startup, shutdown, tool registration, requests.
Debug4Diagnostic detail. Substituted statements, auth context, cache keys.
Configure via server.log_level in .hyperterse, or --log-level / --verbose CLI flags.

​
Log routing

FlagDescription
--log-file <path>Write logs to a file instead of stderr.
--log-tags <tags>Filter output to specific component tags.

​
Attribute redaction

The observability subsystem redacts sensitive values before export:
  • Connection strings — Replaced with [REDACTED] in trace spans.
  • API keys — Auth policy values excluded from trace attributes.
  • Statement parameters — Input values in substituted statements logged at debug level only.
Redaction is applied at the observability contract layer, not per-exporter.

​
Configuration

server:
  log_level: 3
  observability:
    tracing:
      enabled: true
      endpoint: 'http://localhost:4318/v1/traces'
    metrics:
      enabled: true
      endpoint: 'http://localhost:4318/v1/metrics'
When tracing or metrics are not configured, they default to disabled.

​
Collector integration

Hyperterse exports via OTLP over HTTP. Point the endpoint to your collector:
BackendConfiguration
JaegerOTLP receiver on port 4318
Grafana TempoOTLP receiver
Datadog AgentOTLP ingestion endpoint
AWS X-RayADOT collector with OTLP receiver

​
Quick start with Jaeger

docker run -d --name jaeger \
  -p 16686:16686 \
  -p 4318:4318 \
  jaegertracing/all-in-one:latest
Set the tracing endpoint to http://localhost:4318/v1/traces and view traces at http://localhost:16686.