OTLP Protobuf across languages

Shared wire contract

The upstream OpenTelemetry Protobuf schema defines OTLP export messages. The language tabs below show instrumentation and exporter code, not code that Protobuf generates automatically.

All three paths accept Content-Type: application/x-protobuf. Exporters should use Authorization: Bearer <workspace-scoped ingest key>. The traces examples below use https://api.telemio.sh/v1/traces. Standard OTLP SDK exporters can send metrics and logs to their respective paths.

Choose your language

Examples share service.name=checkout-api and emit checkout.complete. Select a language and copy the install and source snippets. Only TypeScript uses the published first-party package.

npm install @telemio/sdk@^0.2.0

import { createTelemio } from "@telemio/sdk";

const telemio = createTelemio({
  endpoint: "https://api.telemio.sh",
  serviceName: "checkout-api",
  apiKey: process.env.TELEMIO_API_KEY,
  otlpProtocol: "http/protobuf", // Opt in to binary Protobuf
});

await telemio.tracer.withSpan("checkout.complete", async span => {
  span.setAttribute("checkout.result", "success");
});
await telemio.metrics.gauge("checkout.active", 12);
await telemio.logger.info("checkout.completed");

python -m pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp-proto-http

import os
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

provider = TracerProvider(resource=Resource.create({"service.name": "checkout-api"}))
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter(
    endpoint="https://api.telemio.sh/v1/traces",
    headers={"Authorization": f"Bearer {os.environ['TELEMIO_API_KEY']}"},
)))
trace.set_tracer_provider(provider)

tracer = trace.get_tracer("checkout-api")
with tracer.start_as_current_span("checkout.complete") as span:
    span.set_attribute("checkout.result", "success")
provider.force_flush()

go get go.opentelemetry.io/otel go.opentelemetry.io/otel/sdk go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp

package main

import (
  "context"
  "log"
  "os"

  "go.opentelemetry.io/otel/attribute"
  "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
  "go.opentelemetry.io/otel/sdk/resource"
  sdktrace "go.opentelemetry.io/otel/sdk/trace"
)

func main() {
  ctx := context.Background()
  key := os.Getenv("TELEMIO_API_KEY")
  if key == "" { log.Fatal("TELEMIO_API_KEY is required") }
  exporter, err := otlptracehttp.New(ctx,
    otlptracehttp.WithEndpointURL("https://api.telemio.sh/v1/traces"),
    otlptracehttp.WithHeaders(map[string]string{
      "Authorization": "Bearer " + key,
    }),
  )
  if err != nil { log.Fatal(err) }
  provider := sdktrace.NewTracerProvider(
    sdktrace.WithBatcher(exporter),
    sdktrace.WithResource(resource.NewSchemaless(
      attribute.String("service.name", "checkout-api"),
    )),
  )
  tracer := provider.Tracer("checkout-api")
  _, span := tracer.Start(ctx, "checkout.complete")
  span.SetAttributes(attribute.String("checkout.result", "success"))
  span.End()
  if err := provider.Shutdown(ctx); err != nil { log.Fatal(err) }
}

cargo add opentelemetry opentelemetry_sdk
cargo add opentelemetry-otlp --features http-proto,reqwest-blocking-client

use std::{collections::HashMap, env};
use opentelemetry::trace::{Span, Tracer, TracerProvider};
use opentelemetry_otlp::{Protocol, WithExportConfig, WithHttpConfig};
use opentelemetry_sdk::{trace::SdkTracerProvider, Resource};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let exporter = opentelemetry_otlp::SpanExporter::builder()
        .with_http()
        .with_endpoint("https://api.telemio.sh/v1/traces")
        .with_protocol(Protocol::HttpBinary)
        .with_headers(HashMap::from([(
            "Authorization".to_string(),
            format!("Bearer {}", env::var("TELEMIO_API_KEY")?),
        )]))
        .build()?;
    let provider = SdkTracerProvider::builder()
        .with_simple_exporter(exporter)
        .with_resource(Resource::builder().with_service_name("checkout-api").build())
        .build();
    let tracer = provider.tracer("checkout-api");
    let mut span = tracer.start("checkout.complete");
    span.set_attribute(opentelemetry::KeyValue::new("checkout.result", "success"));
    span.end();
    provider.shutdown()?;
    Ok(())
}

Schema code generation versus instrumentation

Tools such as Buf compile .proto schemas into typed message definitions. They do not produce tracing middleware, exporters, credential handling, or a native Telemio SDK. For most applications, use the upstream OpenTelemetry SDK and OTLP exporter shown above rather than constructing export messages by hand.

Docs maintainers can regenerate this page from one source using node scripts/generate-otlp-docs.mjs and verify it with node scripts/generate-otlp-docs.mjs --check. This documentation generator uses the canonical OTLP paths and language-specific templates; it does not run protoc.

Verify ingestion

Run the example in a trusted environment and check the Query page in Telemio for a trace named checkout.complete. If it is absent, confirm the HTTPS endpoint, the credential's ingest scope, service authorization, and the application/x-protobuf content type.