Skip to main content
A Span represents a single operation within a trace. Spans are created by tracer.startSpan() or automatically by tracer.trace() and tracer.wrap(). 
import type { Span } from 'dd-trace'

​
Methods

​
setTag(key, value)

Sets a single tag on the span. 
setTag(key: string, value: any): this
​
key
string
required
The tag key.
​
value
any
required
The tag value. Strings, numbers, and booleans are supported.
​
returns
Span
The Span instance, for chaining.
span.setTag('http.status_code', 200)
span.setTag('user.id', '123')
span.setTag('error', true)
Setting error: true marks the span as an error. You can also set error to an Error instance to capture the error message and stack trace.

​
addTags(keyValuePairs)

Sets multiple tags on the span at once. 
addTags(keyValuePairs: { [key: string]: any }): this
​
keyValuePairs
object
required
An object of key-value tag pairs to add to the span.
​
returns
Span
The Span instance, for chaining.
span.addTags({
  'http.method': 'GET',
  'http.url': '/api/users',
  'http.status_code': 200,
})

​
setOperationName(name)

Overrides the operation name of the span. 
setOperationName(name: string): this
​
name
string
required
The new operation name.
​
returns
Span
The Span instance, for chaining.
span.setOperationName('custom.operation')

​
finish(finishTime?)

Finishes the span, marking the end of the operation. After calling finish(), no further modifications to the span should be made. 
finish(finishTime?: number): void
​
finishTime
number
An optional explicit finish time in milliseconds since epoch. Defaults to the current time.
const span = tracer.startSpan('operation')
// ... do work ...
span.finish()

// With explicit finish time
span.finish(Date.now() - 100)
When using tracer.trace() or tracer.wrap(), spans are finished automatically. Only call finish() manually when using tracer.startSpan().

​
log(keyValuePairs, timestamp?)

Adds a log event to the span. 
log(keyValuePairs: { [key: string]: any }, timestamp?: number): this
​
keyValuePairs
object
required
Key-value pairs to log on the span.
​
timestamp
number
Optional timestamp in milliseconds since epoch.
​
returns
Span
The Span instance, for chaining.
span.log({ event: 'error', message: 'something went wrong' })

​
context()

Returns the SpanContext associated with this span. The context is safe to use even after the span has finished. 
context(): SpanContext
​
returns
SpanContext
The SpanContext for this span, containing the trace ID and span ID.
const ctx = span.context()
console.log(ctx.toTraceId()) // e.g. '1234567890abcdef'
console.log(ctx.toSpanId())  // e.g. 'abcdef1234567890'

// Use context for propagation
tracer.inject(ctx, 'http_headers', headers)

​
tracer()

Returns the Tracer instance that created this span. 
tracer(): Tracer
​
returns
Tracer
The Tracer instance.
const t = span.tracer()
const childSpan = t.startSpan('child.op', { childOf: span })
Adds a causal link to another span. Span links express relationships between spans that are not parent-child. 
// Preferred form
addLink(link: { context: SpanContext, attributes?: Object }): void

// Deprecated form
addLink(context: SpanContext, attributes?: Object): void
​
link
object
required
A link object.
Links added after span creation do not affect the sampling decision. Add links at span creation (via SpanOptions.links) when possible.
const producerSpan = tracer.startSpan('producer')
producerSpan.finish()

const consumerSpan = tracer.startSpan('consumer')
consumerSpan.addLink({
  context: producerSpan.context(),
  attributes: { 'messaging.system': 'kafka' },
})
Adds multiple causal links to the span. 
addLinks(links: { context: SpanContext, attributes?: Object }[]): void
​
links
array
required
An array of link objects, each with a context and optional attributes.
span.addLinks([
  { context: span1.context() },
  { context: span2.context(), attributes: { key: 'value' } },
])

Build docs developers (and LLMs) love

Get started for freeTalk to us