Runtime And Retention

Log records are structured JSON records. They include request and trace context when available, plus the stream identity.

Stream Identity

Every log stream uses Layeron’s platform namespace/name identity.

name identifies the stream itself. Use names such as app, database, webhooks, billing, or auth.

Use Namespaces for namespace defaults and naming rules.

The identity makes later views and policies easier to build:

namespace=api name=app
namespace=api name=database
namespace=webhooks name=stripe

Runtime Records

The app Worker sends log records to the Log Product Worker through WorkerEntrypoint RPC. The Product Worker applies sampling and redaction, then emits records through the Layeron observability sink. In the current Cloudflare target, that sink writes to Worker logs.

appLog.info("post created", {
  postId,
  titleLength: title.length,
})

Workers Logs Head Sampling

sampling.success and sampling.error are Layeron record-level policies for a named stream. workerLogs.headSamplingRate maps to Cloudflare Workers Logs head-based sampling for the compiled Worker app.

Use record-level sampling when you want stream behavior such as full error records and lower-volume normal logs:

const appLog = log({
  name: "app",
  namespace: "api",
  sampling: {
    success: 0.25,
    error: 1,
  },
})

Use Workers Logs head sampling when you want Cloudflare to sample whole Worker invocations:

const appLog = log({
  name: "app",
  namespace: "api",
  workerLogs: {
    headSamplingRate: 0.5,
  },
})

Retention

Workers Logs are the default short-term view. When a stream needs retained history, declare archive retention:

const appLog = log({
  name: "app",
  namespace: "api",
  retention: {
    mode: "archive",
    days: 30,
  },
})

Layeron lowers this to a layeron.log.archive resource and a generated Storage bucket instance. The Log Product Worker writes retained records through Storage Product RPC, and Storage owns the R2 bucket, binding, lifecycle, and future archive integrations. The archive is partitioned by workspace, project, environment, date, namespace, and name, so the CLI can query retained records.

Use the CLI to read retained records:

layer logs list . --env production --namespace api --name app --since 1h

Integrations

The current implementation uses:

• Cloudflare Workers for runtime execution.
• Cloudflare WorkerEntrypoint RPC for app-to-product calls.
• Worker observability settings on the compiled Worker app.
• Cloudflare Workers Logs for structured log records.
• Layeron Storage backed by Cloudflare R2 for retained log archives when retention.mode is archive.

Future pipeline work can add Analytics Engine aggregations, R2 Catalog metadata, or a Tail Worker without changing the log API.