For agents: start with the agent guide. Every page is Markdown by default; add Accept: text/html for HTML.

Trace operations where they mean something

Telemetry means logs, metrics, and traces.¶

Name the operation a person needs to understand. Add only context safe for that operation’s telemetry.¶

A tracing span records an operation’s timing and outcome. Export is a separate delivery step.¶

Name meaningful operations

FileInspector.inspect uses a named Effect.fn:¶

  {
    readonly inspect: (
      path: string
    ) => Effect.Effect<FileStats, FileStatsError>;
  }
>()("@rat-stack/core/FileInspector", {
  make: Effect.gen(function* makeFileInspector() {
    const fileSystem = yield* FileSystem.FileSystem;

    const inspect = Effect.fn("FileInspector.inspect")(function* inspect(
      path: string
    ) {
      const content = yield* fileSystem
        .readFile(path)
        .pipe(
          Effect.mapError(
            (error) => new FileStatsError({ path, reason: error.message })
          )

Use a named fn for a reusable operation that deserves a span. Use withSpan around an existing Effect when that boundary carries useful meaning. Use fnUntraced for reusable functions that do not need tracing, especially small library functions and frequently executed code.¶

Do not create a span merely because a helper exists. Choose boundaries that answer a question about the job’s duration, dependencies or failure.¶

Add safe attributes deliberately

A span name should remain stable across requests. Put safe variation in attributes instead of generating a new name for every input. Keep unrestricted input, credentials, request bodies and private identities out of telemetry.¶

Structured attributes can outlive the request. Structure does not make a private value safe.¶

Use annotateCurrentSpan when adding attributes inside the operation. Use annotateSpans when supplying annotations through an enclosing Effect. Review the resulting payload as well as the annotation call.¶

Supply an exporter, serializer and transport

The exporter prepares trace data. The serializer encodes it. The transport sends it.¶

OTLP means OpenTelemetry Protocol. A collector receives trace data.¶

The checked fixture composes the OTLP tracer with JSON serialization and an in-memory HTTP client:¶

      const tracing = OtlpTracer.layer({
        resource: { serviceName: "wiki-fixture" },
        url: "https://collector.example.test/v1/traces",
      }).pipe(
        Layer.provide(OtlpSerialization.layerJson),
        Layer.provide(Layer.succeed(HttpClient.HttpClient, client))
      );

      yield* Effect.scoped(
        Effect.void.pipe(
          Effect.withSpan("fixture.read"),
          Effect.annotateSpans({ phase: "read" }),
          Effect.provide(tracing)
        )
      );

These observability modules are marked unstable in the exact 4.0.0 source. A stable package version does not make every exported module’s API stable. Keep the exact pin and check its source before changing exporter composition.¶

Check the delivery boundary you actually exercised

The fixture’s transport decodes outbound JSON through a small Schema. It records the payload in a Ref instead of contacting a collector. After shutdown, the test requires the operation name and the annotation key.¶

      const spans = (yield* Ref.get(deliveries)).flatMap((delivery) =>
        delivery.resourceSpans.flatMap((resource) =>
          resource.scopeSpans.flatMap((scope) => scope.spans)
        )
      );

      expect(spans.map((span) => span.name)).toContain("fixture.read");
      expect(
        spans.flatMap((span) =>
          span.attributes.map((attribute) => attribute.key)
        )
      ).toContain("phase");
    })

The fixture observes a serialized export request. It does not prove backend acceptance, storage, or a production exporter configuration.¶

None of these observations substitutes for the next delivery boundary.¶

Native tracing includes platform data

TRACES_ENABLED defaults to false. TRACES_HEAD_SAMPLING_RATE defaults to 0.01 and accepts finite values from zero through one.¶

The Effect tracer drops arbitrary attributes, events and links. Its native completion attribute records only a fixed outcome. Its tests cover this boundary. They do not prove privacy for Cloudflare’s automatic spans.¶

Cloudflare documents these automatic fields:¶

Full URLs and query strings can contain tokens or email addresses. SQL bindings, storage keys and custom metadata can contain private values. The Effect attribute policy does not redact these platform fields.¶

For outbound fetch, the listed headers include content-type, content-length, accept and accept-encoding. Fetch handlers also list accept-language.¶

The documentation lists body sizes. Body contents, Authorization values and Cookie values are absent from that list. That list does not prove that all runtime versions omit other fields. The representation of R2 encryption-key-related fields remains unverified here.¶

Owner approval is required before enabling native traces. Review this list and the authenticated plan before changing the flag. A low sampling rate reduces collection volume. It does not make captured private values safe.¶

Mischief and RpcBackend register a per-event telemetry Layer. The Website builds its native tracer inside each request. Its development and prerender paths work without the Cloudflare runtime. These Layers retain no request tracer or async-context map across requests.¶

Keep other observers distinct

Devtools⁷ records capability calls and watched actor lifecycles. Request analytics¹⁸ captures request events through its own sink. Neither system substitutes for trace-export evidence.¶

Logs also have their own logger and export configuration. Do not claim a log was delivered because it appeared in a local console.¶

Common mistakes

• Assume naming a span installs a collector.¶
• Treat a test transport as a live backend.¶
• Put every argument into telemetry for convenience.¶
• Copy exporter settings from a different Effect version without checking its dependencies.¶

Effect idiom and house rule

• Instrument meaningful operations and compose explicit observability Layers where the application starts and runs Effects.¶
• In rat-stack, keep private values scoped and report each observed delivery boundary honestly.¶
• In rat-stack, actor watching and capability recording remain their own devtools paths.¶

Next, run Effect at the integration boundary⁸ and connect observability lifetime to its runtime owner. Return to the Effect reading order¹⁷.¶

Last changed 2026-10-08 in 29ccee3. Source on GitHub. Change log.

Content updated 2026-10-09.