A span is one timed operation inside a trace, such as an HTTP request, a database query or a function call, with a name, a start and end time, attributes, events and a status.
What a span contains
A database query recorded by the orders service, as an OpenTelemetry span:
name: SELECT orders
kind: CLIENT
trace_id: 4bf92f3577b34da6a3ce929d0e0e4736
span_id: a3ce929d0e0e4736
parent_span_id: 00f067aa0ba902b7
start: 2026-11-21T10:15:02.038Z
end: 2026-11-21T10:15:02.052Z (14 ms)
status: UNSET
attributes:
db.system.name: postgresql
db.operation.name: SELECT
db.collection.name: orders
server.address: db-primary.internal
resource:
service.name: orders-service
service.version: 2.14.0 - Name: a low-cardinality description of the operation, such as
GET /orders/{id}orSELECT orders. Never put IDs in a span name. - Trace ID and span ID: which trace the span belongs to, and its own identity.
- Parent span ID: the span that caused this one. Empty on the root span.
- Start and end time: the duration is the difference.
- Attributes: key-value details about the operation, named by the semantic conventions where one exists.
- Events: timestamped points inside the span. A recorded exception is an event.
- Links: references to spans in other traces, for example from a batch job to each message it processed.
- Status:
UNSET,OKorERROR. - Resource: who produced it, such as
service.nameand the host. Shared by every span from the same process.
Span kinds
The kind says how a span relates to other processes. SERVER handles an incoming request and CLIENT makes an outgoing one, so one HTTP call between two services produces a client span in the caller and a server span in the receiver. PRODUCER and CONSUMER are the same pair for messages sent through a queue. INTERNAL, the default, is work inside one process. Backends use kinds to draw service maps and to count requests, so getting them right matters more than it looks.
Status: leave it unset on success
Instrumentation sets ERROR when an operation fails, for example a 5xx response on a server span. It leaves successful spans UNSET. OK is for an application that wants to override an error decision explicitly, and is rarely needed. A 404 on a client span is an error for that call, while a 404 on a server span is usually the client's mistake and is left unset.
Creating a span by hand
Auto-instrumentation creates spans for HTTP, database and queue calls. For your own business logic, wrap the operation yourself. In Node.js:
import { trace, SpanStatusCode } from "@opentelemetry/api";
const tracer = trace.getTracer("orders");
export async function chargeCard(order) {
return tracer.startActiveSpan("charge card", async (span) => {
span.setAttribute("order.id", order.id);
try {
return await payments.charge(order);
} catch (error) {
span.recordException(error);
span.setStatus({ code: SpanStatusCode.ERROR });
throw error;
} finally {
span.end();
}
});
} startActiveSpan makes the span current, so spans created inside it, such as the HTTP call to the payment provider, become its children. Always end the span, including on the error path; a span that never ends is never exported.