Tracing¶
Tracing is built on the official OpenTelemetry SDK of each language. This SDK adds a common
setup function with the right exporter defaults for Apache SkyWalking, span helpers, propagation,
framework adapters and — when Apache SkyWalking has a query API — a TraceQueryClient to read traces
back. The service setup function (initTracing) and the query client accessor are described on
Functions.
Set up¶
initTracing(config) installs a tracer provider (globally unless setGlobal is false) and returns
a TracingHandle with tracer(name), forceFlush() and an idempotent shutdown().
| Setting | Default | Notes |
|---|---|---|
serviceName |
required | service.name resource attribute |
serviceVersion, environment, resourceAttributes |
none | service.version, deployment.environment, extra attributes |
endpoint, protocol |
Apache SkyWalking defaults | grpc, http/protobuf or native |
headers |
none | auth headers are redacted in toString |
sampler, samplerRatio |
parentbased_always_on, 1.0 |
also always_on, always_off, traceidratio, parentbased_always_off, parentbased_traceidratio |
propagators |
tracecontext, baggage |
b3, b3multi, datadog, sw8 where supported |
batch |
queue 2048, batch 512, delay 5 s, timeout 30 s | span batch processor |
compression |
gzip |
or none |
tls, setGlobal |
none, true |
Always call shutdown() before the process exits so queued spans are exported.
Spans¶
| Helper | What it does |
|---|---|
withSpan(name, fn, { attributes, kind, links, tracer }) |
runs fn in a new span; records the exception and sets ERROR status on failure, then rethrows |
traced |
wraps a function (decorator/annotation where the language has one) |
currentSpan(), currentTraceId(), currentSpanId() |
the active span and its ids (lower-case hex) |
addEvent(name, attributes?), recordException(error), setError(error) |
act on the active span |
traceFields() |
{ trace_id, span_id } for log correlation (snake_case on purpose) |
import { addEvent, traced, withSpan } from "@grow-codes/apache-skywalking";
const total = await withSpan("checkout.total", async (span) => {
span.setAttribute("cart.items", 3);
addEvent("prices.loaded");
return computeTotal();
}, { attributes: { "cart.id": "c-1" } });
const charge = traced(async (amount: number) => pay(amount), "checkout.charge");
class Orders {
@traced("orders.create")
async create() { /* … */ }
}
use grow_apache_skywalking::tracing::{add_event, traced, with_span, SpanOptions};
let total = with_span("checkout.total", SpanOptions::default(), async {
add_event("prices.loaded", Default::default());
compute_total().await
})
.await?;
let charged = traced("checkout.charge", pay(42)).await?;
// or annotate functions with #[tracing::instrument] and use the otel_layer() bridge
total, err := skywalking.WithSpan(ctx, "checkout.total", func(ctx context.Context) (int, error) {
skywalking.AddEvent(ctx, "prices.loaded", nil)
return computeTotal(ctx)
}, skywalking.WithSpanAttributes(map[string]any{"cart.id": "c-1"}))
err = skywalking.Traced(ctx, "checkout.charge", func(ctx context.Context) error {
return pay(ctx, 42)
})
Propagation¶
inject(carrier) writes the current context into a string map (for example message headers) and
extract(carrier) reads it back. injectHeaders/extractHeaders do the same for HTTP headers.
Framework adapters¶
| Language | Adapters |
|---|---|
| TypeScript | Express middleware, Fastify plugin, NestJS interceptor, tracedFetch(fetch) |
| Rust | otel_layer() for tracing-opentelemetry, tower TraceLayer (axum, hyper; feature tower), TracingMiddleware for reqwest-middleware (feature reqwest-middleware) |
| Go | HTTPMiddleware (server) and HTTPTransport (http.RoundTripper); gRPC interceptors in grpcadapter |
| Python | TracingASGIMiddleware, TracingWSGIMiddleware, httpx_event_hooks(), instrument_requests_session() |
| Java | Servlet Filter (jakarta.servlet), TracedHttpClient for java.net.http, OkHttp Interceptor |
Read traces back¶
TraceQueryClient is available when Apache SkyWalking has a query API (otherwise its methods raise
UNSUPPORTED; see Compatibility). Ids are lower-case hex; 64-bit trace ids
are left-padded to 32 characters.
| Function | Returns |
|---|---|
getTrace(traceId) |
Trace { traceId, spans } (spans sorted by start time) or null |
searchTraces(query) |
TraceSummary[]; query: service, operation, tags, minDuration, maxDuration, start, end, limit (20) |
listServices() / listOperations(service) |
names |
getDependencies({ start, end }) |
DependencyLink { parent, child, callCount }[] |
waitForTrace(traceId, { timeout, interval, minSpans }) |
Trace once it has minSpans spans; TIMEOUT otherwise |
buildTree(spans) turns the flat span list into a parent/child tree.
Testing¶
The testing module has an in-memory span exporter and trace query client (see Docker testing).