Tracing

@granit/tracing provides framework-agnostic OpenTelemetry utilities for browser tracing — mirroring Granit.Observability on the .NET backend. It exports a getTraceContext() function that reads the active span’s trace and span IDs for correlation with @granit/logger-otlp.

@granit/react-tracing wraps this into a TracingProvider that initializes the OpenTelemetry WebTracerProvider with auto-instrumentations (fetch, XHR, document-load) and an OTLP HTTP exporter, plus hooks for creating custom spans.

Peer dependencies: @opentelemetry/api, @opentelemetry/sdk-trace-web, @opentelemetry/exporter-trace-otlp-http, react ^19

Package structure

• Directory@granit/tracing/ TraceContext type, getTraceContext utility (framework-agnostic)

  • @granit/react-tracing TracingProvider, useTracer, useSpan hooks

Package	Role	Depends on
@granit/tracing	getTraceContext(), TraceContext, TracingConfig	@opentelemetry/api
@granit/react-tracing	TracingProvider, useTracer, useSpan	@granit/tracing, @opentelemetry/sdk-trace-web, @opentelemetry/exporter-trace-otlp-http, react

Setup

React (recommended)

import { TracingProvider } from '@granit/react-tracing';

function App({ children }) {
  return (
    <TracingProvider config={{
      serviceName: 'guava-front',
      serviceVersion: '1.0.0',
      exporter: { url: '/v1/traces' },
    }}>
      {children}
    </TracingProvider>
  );
}

TypeScript only

import { getTraceContext } from '@granit/tracing';
import type { TraceContext, TracingConfig } from '@granit/tracing';

const ctx = getTraceContext();
// { traceId: '...', spanId: '...' } or undefined

TypeScript SDK

Types

interface TraceContext {
  traceId: string;
  spanId: string;
}

interface TracingExporterConfig {
  url: string;
  headers?: Record<string, string>;
}

interface TracingConfig {
  serviceName: string;
  serviceVersion?: string;
  exporter: TracingExporterConfig;
  instrumentFetch?: boolean;              // default: true
  instrumentXhr?: boolean;                // default: true
  instrumentDocumentLoad?: boolean;       // default: true
  additionalInstrumentations?: Instrumentation[];
}

getTraceContext()

Reads the active span from the OpenTelemetry global context. Safe to call from non-React code — used as the getTraceContext callback for @granit/logger-otlp.

function getTraceContext(): TraceContext | undefined;

React bindings

Framework-agnostic core

The getTraceContext() function and types live in @granit/tracing — pure TypeScript. The React package below initializes the OpenTelemetry SDK and provides span hooks.

TracingProvider

Initializes the OpenTelemetry WebTracerProvider with:

• Auto-instrumentations: fetch, XMLHttpRequest, document-load
• OTLP HTTP exporter with gated startup (probes the collector — if unavailable, disables export for the session with a warning instead of continuous errors)
• Graceful shutdown on unmount (flushes pending spans)

<TracingProvider config={{
  serviceName: 'guava-front',
  exporter: { url: '/v1/traces' },
}}>
  {children}
</TracingProvider>

useTracer()

Returns the OpenTelemetry Tracer instance from the provider.

function useTracer(): Tracer;

useSpan()

Helpers for creating custom spans within React components.

interface UseSpanReturn {
  withSpan: <T>(name: string, fn: (span: Span) => T | Promise<T>) => Promise<T>;
  createSpan: (name: string, options?: SpanOptions) => Span;
}

function useSpan(): UseSpanReturn;

• withSpan — Executes a function within a new span. The span is automatically ended on completion or rejection. Errors are recorded on the span.
• createSpan — Creates a span for manual control. You must call span.end() yourself.

Public API summary

Category	Key exports	Package
Types	TraceContext, TracingConfig, TracingExporterConfig	@granit/tracing
Utility	getTraceContext()	@granit/tracing
Provider	TracingProvider	@granit/react-tracing
Hooks	useTracer(), useSpan()	@granit/react-tracing

See also

• Granit.Observability module — .NET Serilog + OpenTelemetry → OTLP
• Logger — @granit/logger-otlp uses getTraceContext() for log-trace correlation