Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.hyperterse.com/llms.txt

Use this file to discover all available pages before exploring further.

Hyperterse integrates with OpenTelemetry for distributed tracing and metrics. Tracing covers the execution path, database connectors, and MCP traffic. Structured logging provides operational visibility at every level.

​
Tracing

When tracing is on, Hyperterse records 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

Sensitive values are redacted 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.