Record types

Choose a record type based on the question you want to answer.

Counters

Use increment(...) for values that increase over time:

runtime.increment("posts.list.requests")
runtime.increment("jobs.email.processed", 1, { queue: "email" })

Good examples are request counts, processed job counts, retry counts, and webhook delivery attempts.

Gauges

Use gauge(...) for values that can go up or down:

runtime.gauge("jobs.email.pending", pendingCount)

Good examples are queue depth, open connection count, and active worker count.

Histograms

Use histogram(...) for distributions:

runtime.histogram("payload.bytes", size)

Good examples are payload size, batch size, and rows returned.

Timings

Use timing(...) to measure callback duration:

const posts = await runtime.timing("posts.list.duration_ms", () => {
  return listPosts()
})

The method returns the callback result.

Events

Use event(...) for named activity:

runtime.event("posts.created", { postId: post.id })

Good examples are post.created, webhooks.stripe.replayed, and jobs.email.completed.

Signals

Use signal(...) for numeric operational values:

runtime.signal("db.shard.hotness", 0.82, { shard: "shard-1" })

Signals are useful for product internals and operational pressure values.

Errors

Use capture(...) for errors:

try {
  await handleStripeWebhook(request)
} catch (error) {
  runtime.capture(error, { provider: "stripe" })
  throw error
}

Captured errors share the stream context and attributes.

Spans

Use span(...) to wrap a named operation:

await runtime.span("webhooks.stripe.handle", () => {
  return handleStripeWebhook(request)
})

Layeron emits one span record when the callback finishes.

Span records include spanId, parentSpanId when the span is nested, traceId when the request has one, duration, and outcome.