opentelemetry

opentelemetry — go-ruby-opentelemetry

A pure-Go (no cgo), MRI-faithful reimplementation of Ruby's opentelemetry-api and opentelemetry-sdk gems — distributed tracing: tracers, spans, span context, W3C context propagation, baggage, span processors, samplers and an exporter seam. It mirrors opentelemetry-ruby's observable surface (in_span, start_span, set_attribute, add_event, record_exception, status=, TraceContext inject/extract) while delegating the tracing model to the real, well-tested OpenTelemetry Go SDK.

It is the OpenTelemetry backend for go-embedded-ruby, but is a standalone, reusable module — a sibling of go-ruby-json and go-ruby-set.

Does not reimplement the tracing model. Every type is a Ruby-faithful facade over go.opentelemetry.io/otel and go.opentelemetry.io/otel/sdk: the Go SDK does the recording, sampling, batching and W3C traceparent/tracestate/baggage serialization; this module re-expresses it with opentelemetry-ruby method names and semantics.

In-process, zero network. The span exporter is an injectable seam. An InMemorySpanExporter is provided for tests and embedding; OTLP/stdout exporters are a documented follow-up.

Install

go get github.com/go-ruby-opentelemetry/opentelemetry

Usage

package main

import (
	"errors"
	"fmt"

	rbcontext "github.com/go-ruby-opentelemetry/opentelemetry/context"
	"github.com/go-ruby-opentelemetry/opentelemetry/propagation"
	sdktrace "github.com/go-ruby-opentelemetry/opentelemetry/sdk/trace"
	"github.com/go-ruby-opentelemetry/opentelemetry/trace"
)

func main() {
	// SDK::Trace::TracerProvider with a simple processor + in-memory exporter.
	exporter := sdktrace.NewInMemorySpanExporter()
	tp := sdktrace.NewTracerProvider(
		sdktrace.WithSpanProcessor(sdktrace.NewSimpleSpanProcessor(exporter)),
		sdktrace.WithSampler(sdktrace.AlwaysOn()),
	)
	tracer := tp.Tracer("my.service", "1.0.0")

	// Tracer#in_span(name, attributes:, kind:) { |span| ... }
	tracer.InSpan(rbcontext.Background(), "handle-request",
		func(span trace.Span, ctx *rbcontext.Context) {
			span.SetAttribute("http.method", "GET")
			span.AddEvent("cache.miss", map[string]any{"key": "u:42"})
			span.RecordException(errors.New("upstream slow"), nil)
			span.SetStatus(trace.StatusError("degraded"))

			// W3C TraceContext inject → extract round-trips the ids + flags.
			carrier := propagation.NewCarrier()
			propagation.TraceContext().Inject(ctx, carrier)
			fmt.Println(carrier["traceparent"])
		},
		trace.WithKind(trace.Server),
	)

	finished := exporter.FinishedSpans()
	fmt.Println(finished[0].Name(), finished[0].Status().Code) // handle-request Error
}

Ruby surface

What it consumes

• go.opentelemetry.io/otel/trace — the tracing API model (spans, span context, kind).
• go.opentelemetry.io/otel/sdk/trace — the tracer provider, processors, samplers.
• go.opentelemetry.io/otel/propagation — W3C TraceContext + Baggage propagators.
• go.opentelemetry.io/otel/baggage — the baggage container.
• tracetest.InMemoryExporter — backs the in-memory exporter seam.

Correctness

Verified against the backing Go SDK semantics with the in-memory exporter, fully in-process (no network):

• spans record the correct name, attributes, events, status, kind and parent/child linkage (child shares the parent's trace_id and carries the parent's span_id);
• W3C TraceContext inject → extract round-trips trace_id, span_id and trace_flags, and marks the extracted context remote?;
• baggage round-trips through the W3C baggage header;
• sampling decisions are honored (AlwaysOn, AlwaysOff, ParentBased, ratio-based);
• both the simple and batch processors flush to the exporter;
• in_span records a panic as an exception event, sets the status to error, and re-raises.

Tests & coverage

COVERPKG=$(go list ./... | paste -sd, -)
go test -race -coverpkg="$COVERPKG" -coverprofile=cover.out ./...
go tool cover -func=cover.out | tail -1   # 100.0%

CGO-free, gofmt + go vet clean, race-clean, and green across the six 64-bit Go targets (amd64, arm64, riscv64, loong64, ppc64le, s390x big-endian) and three OSes (Linux, macOS, Windows). Span timestamps are the SDK's monotonic UTC clocks — no timezone assumptions.

Follow-ups

• Metrics (OpenTelemetry::Metrics — meters/instruments) — a documented follow-up; this module does the trace API + SDK faithfully.
• OTLP / stdout exporters wired onto the existing SpanExporter seam.
• rbgo binding into go-embedded-ruby.
• Full org conformance (Hugo landing, MkDocs/mike docs, brand assets).

License

BSD-3-Clause — see LICENSE. Copyright the go-ruby-opentelemetry/opentelemetry authors.

WebAssembly

Being pure Go (CGO=0), this library also compiles to WebAssembly — both GOOS=js GOARCH=wasm (browser / Node.js) and GOOS=wasip1 GOARCH=wasm (WASI). CI builds both targets on every push, alongside the six 64-bit native/qemu arches.

GOOS=js     GOARCH=wasm go build ./...   # browser / Node
GOOS=wasip1 GOARCH=wasm go build ./...   # WASI (wasmtime, wasmer, wasmedge, …)