Documentation / @agentick/core / Span

Interface: Span

Defined in: kernel/src/telemetry.ts:81

A span represents a unit of work or operation within a trace. Spans track timing, attributes, and errors for observability.

The core methods (end, setAttribute, recordError) are required. The remaining methods are optional so that older TelemetryProvider implementations remain valid; callers should invoke them with ?.() and tolerate undefined returns. New providers should implement all of them for full feature support.

Examples

const span = Telemetry.startSpan('database-query');
try {
  span.setAttribute('query', 'SELECT * FROM users');
  const result = await db.query(...);
  span.setAttribute('rowCount', result.length);
  span.setStatus?.({ code: 'ok' });
} catch (error) {
  span.recordError(error);
  throw error;
} finally {
  span.end();
}

// Don't clobber whatever the engine set; only add what's missing.
if (span.getAttribute?.('tool.name') === undefined) {
  span.setAttribute('tool.name', resolvedName);
}

span.addEvent?.('llm_request_sent', { model: 'gpt-4' });
const response = await llm.invoke(...);
span.addEvent?.('llm_response_received', { tokens: response.usage.total });

Properties

spanId?

readonly optional spanId: string

Defined in: kernel/src/telemetry.ts:94

Unique ID for this span. Used for cross-system log correlation.

---

traceId?

readonly optional traceId: string

Defined in: kernel/src/telemetry.ts:92

Trace ID this span belongs to. Used for cross-system log correlation.

Methods

addEvent()?

optional addEvent(name, attributes?, timestamp?): void

Defined in: kernel/src/telemetry.ts:128

Record a point-in-time event within this span. Cheaper than spawning a nested span when only the moment matters, not a duration.

Parameters

name

string

attributes?

Record<string, AttributeValue>

timestamp?

number

Returns

void

---

end()

end(endTime?): void

Defined in: kernel/src/telemetry.ts:84

End the span, recording its duration.

Parameters

endTime?

number

Returns

void

---

getAttribute()?

optional getAttribute(key): AttributeValue | undefined

Defined in: kernel/src/telemetry.ts:119

Read back a previously-set attribute. Lets middleware enrich the span without clobbering values stamped by the engine or other middleware.

Parameters

key

string

Returns

AttributeValue | undefined

---

getAttributes()?

optional getAttributes(): Readonly<Record<string, AttributeValue>>

Defined in: kernel/src/telemetry.ts:121

Read-only snapshot of all attributes set on this span.

Returns

Readonly<Record<string, AttributeValue>>

---

isRecording()?

optional isRecording(): boolean

Defined in: kernel/src/telemetry.ts:102

Whether the span is still recording. Returns false after end(), when the provider sampled the span out, or when the provider is a no-op. Useful for short-circuiting expensive attribute computation.

Returns

boolean

---

recordError()

recordError(error): void

Defined in: kernel/src/telemetry.ts:88

Record an error that occurred during this span.

Parameters

error

any

Returns

void

---

setAttribute()

setAttribute(key, value): void

Defined in: kernel/src/telemetry.ts:86

Set an attribute on the span for filtering/analysis.

Parameters

key

string

value

any

Returns

void

---

setAttributes()?

optional setAttributes(attrs): void

Defined in: kernel/src/telemetry.ts:114

Set multiple attributes in a single call.

Parameters

attrs

Record<string, AttributeValue>

Returns

void

---

setStatus()?

optional setStatus(status): void

Defined in: kernel/src/telemetry.ts:135

Explicitly set the span's status. Overrides the implicit status from recordError. Standard OTel pattern.

Parameters

status

SpanStatus

Returns

void

---

updateName()?

optional updateName(name): void

Defined in: kernel/src/telemetry.ts:110

Refine the span's name. Useful when an initial name is generic (e.g., http.request) and a more specific one is known later (e.g., POST /v1/query).

Parameters

name

string

Returns

void