Getting started

This guide adds one observability stream to a Layeron backend app.

You will create the stream, register it, count requests, measure a function, record an event, and capture an error.

Create A Stream

import { backend } from "@layeron/core"
import { observability } from "@layeron/modules"

const app = backend()

const runtime = observability({
  name: "runtime",
  namespace: "api",
})

app.use(runtime)

The stream identity is api/runtime. See Namespaces for platform namespace defaults and naming rules.

Count Requests

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

app.get("/posts", async () => {
  runtime.increment("posts.list.requests")

  return Response.json({ posts: await listPosts() })
})

Measure Duration

Use timing(...) around work that can become slow:

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

  return Response.json({ posts })
})

timing(...) returns the callback result.

Record An Event

Use event(...) for an activity that happened once:

app.post("/posts", async (request) => {
  const input = await request.json() as { title: string }
  const post = await createPost(input)

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

  return Response.json({ post }, { status: 201 })
})

Capture An Error

Use capture(...) inside a catch block:

app.post("/webhooks/stripe", async (request) => {
  try {
    await handleStripeWebhook(request)
    runtime.event("webhooks.stripe.delivered")

    return Response.json({ ok: true })
  } catch (error) {
    runtime.capture(error, {
      provider: "stripe",
      route: "/webhooks/stripe",
    })

    throw error
  }
})

Keep secrets, tokens, cookies, and raw provider payloads out of attributes.

Run The App

layer dev .

The current Cloudflare runtime target emits structured observability records through Cloudflare Workers Logs.

Next Steps

• Core concepts: Understand stream identity, records, context, attributes, and sinks.
• Record types: Choose counters, gauges, histograms, timings, events, signals, errors, or spans.
• Sampling and redaction: Control telemetry volume and sensitive attribute handling.
• Runtime model: See declaration flow, runtime attachment, spans, Cloudflare targets, and local tests.
• API reference: Review Observability options and module methods.