telemetry

Telemetry

Overview

Telemetry is a comprehensive observability framework that provides unified telemetry across languages. Instrument your code once with a single fluent API and get structured logging, distributed tracing, metrics collection, and continuous profiling — exported over standard OTLP and, optionally, recorded to MCAP for offline analysis in Foxglove Studio.

Every SDK shares the same mental model: build an Telemetry instance from a config file or code, then use the logger, metrics, and tracer it exposes. The same telemetry.toml drives all four languages.

Features

• Structured logging — context-aware logging with automatic trace correlation.
• Per-module log levels — fine-grained verbosity control per service or module.
• Metrics collection — counters, histograms, and gauges with OpenTelemetry.
• Distributed tracing — end-to-end request tracking across service boundaries.
• Continuous profiling — production performance analysis with Pyroscope.
• MCAP recording — a single file for offline analysis in Foxglove Studio.
• Config-first — auto-discovers telemetry.toml; TOML, YAML, JSON, and environment-variable overrides are all supported.
• Zero-config defaults — sensible defaults get you running with no setup.
• OpenTelemetry native — standard OTLP protocols for maximum compatibility.

Architecture

Language support

Four first-class SDKs share one configuration format and one API shape. Expand a language for installation and a quick start.

Go

go get github.com/the-protobuf-project/telemetry/telemetry-go

package main

import "github.com/the-protobuf-project/telemetry/telemetry-go"

func main() {
    // Auto-discovers telemetry.toml or uses defaults.
    p, err := telemetry.New().
        WithService("my-service", "1.0.0").
        Build()
    if err != nil {
        panic(err)
    }
    defer p.Close()

    p.Logger.Info("Service started")
}

See the Go SDK documentation.

Python

pip install "git+https://github.com/the-protobuf-project/telemetry.git#subdirectory=telemetry-py"

from telemetry import Telemetry

with Telemetry.new().build() as o:
    o.logger.info("Service started")
    o.logger.warning("Rate limit approaching", {"percent": 85})

See the Python SDK documentation.

Rust

[dependencies]
telemetry = { git = "https://github.com/the-protobuf-project/telemetry.git" }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
anyhow = "1.0"

use telemetry::{Telemetry, Environment, logger};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Auto-discovers telemetry.toml config.
    let _telemetry = Telemetry::new()
        .with_service("my-service", "1.0.0")
        .environment(Environment::Production)
        .build()?;

    logger::info!("Service started");
    Ok(())
}

See the Rust SDK documentation.

C++

Add the module dependency in your MODULE.bazel:

bazel_dep(name = "telemetry.cpp", version = "1.0.0")

#include <telemetry/telemetry.hpp>

int main() {
    auto o = telemetry::Telemetry::builder("my-service", "1.0.0")
        .environment(telemetry::Environment::Development)
        .build();

    TELEMETRY_LOG_INFO("Service started");
    o.metrics().counter("requests_total", 1.0);

    auto span = o.tracer().start_span("process_request");
    span.set_attribute("user_id", "12345");
    span.end();
}

See the C++ SDK sources and examples.

Configuration — telemetry.toml

All SDKs auto-discover telemetry.toml from your project root:

[service]
name = "my-service"
version = "1.0.0"
environment = "development"

[telemetry.otlp]
endpoint = "otel.example.com"   # Port 4317 auto-added
auth_token = "your-token"

[logging]
level = 2                        # Global log level (1=Error, 2=Info, 3=Debug)

[logging.modules.nats-module]
level = 1                        # Override: Error only for this module

Precedence (lowest to highest): Defaults → telemetry.toml → .env / TELEMETRY_* environment variables → code.

See the full Configuration Guide.

Environment variables

Every config key can be overridden with an TELEMETRY_-prefixed environment variable. Nesting is expressed with a single underscore in Go, Rust, and C++, and a double underscore in Python.

export TELEMETRY_SERVICE_NAME=my-service
export TELEMETRY_TELEMETRY_OTLP_ENDPOINT=otel.example.com:4317
export TELEMETRY_LOGGING_MODULES_VISION_LEVEL=3

Telemetry signals

Observability stack

Telemetry ships a complete, pre-configured stack in telemetry-core, powered by industry-standard tools:

• Loki — log aggregation
• Tempo — distributed tracing
• Prometheus — metrics storage
• Pyroscope — continuous profiling
• Grafana — unified dashboards
• OpenTelemetry Collector — telemetry pipeline

cd telemetry-core
docker compose up -d

Grafana is then available at http://localhost:3000 with all datasources pre-configured.

Observability stack → · Production deployment →

Repository layout

Development

Each SDK is self-contained and can be built and tested independently.

# Go
cd telemetry-go && go build ./... && go test ./...

# Rust
cd telemetry-rs && cargo build --all-targets && cargo test

# Python
cd telemetry-py && pip install . && ruff check .

# C++ (Bazel)
cd telemetry-cpp && bazel build //...

Continuous integration builds and tests all four SDKs and validates the observability stack. See .github/workflows for the CI and release pipelines.

Use cases

• Microservices — track requests across service boundaries.
• API services — monitor performance and errors.
• Robotics — record and analyze system behavior with MCAP.
• ML pipelines — trace data-processing workflows.
• Production debugging — correlate logs, traces, and metrics.

Contributing

Contributions are welcome. Fork the repository, create a feature branch, make your changes, and open a pull request. Please ensure the relevant SDK builds and its tests and linters pass before submitting.

License

Licensed under the Apache License, Version 2.0.