[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7808RHWDVHJ42VFA2TG12ZP":3,"skill-same:01M7808RHWDVHJ42VFA2TG12ZP":45},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":30,"install":31,"resources":44},"01M7808RHWDVHJ42VFA2TG12ZP","effect-v4-observability",null,"Use when adding logging, metrics, tracing\u002Fspans, or OpenTelemetry to Effect v4 code — covers Effect.fn named spans, the Effect.log* family, custom loggers (Logger.make for the format, Logger.withConsoleLog\u002FwithConsoleError for the route — never a hand-written Console.log call), Metric counters\u002Fgauges\u002Fhistograms with Metric.withAttributes (NOT the removed Metric.tagged), and wiring OpenTelemetry export at the app edge (core OTLP layers in effect\u002Fobservability, Tracer.externalSpan and HttpTraceContext for inbound context, HttpClient.TracerPropagationEnabled for outbound, @effect\u002Fopentelemetry only as an optional SDK bridge). Encodes the house rule that pure-tier libraries instrument public fallible boundaries only and stay telemetry-agnostic, while apps compose OTel at the infrastructure layer.","spencerbeggs\u002Feffected","spencerbeggs","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F109114?v=4","01M77ZTHB70K5Y2VVTRCFY50A5","C. Spencer Beggs","01M77ZTHCC41NXBT3X906K6QM1",8,"MIT","https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fbuilds\u002Fcopilot\u002Fskills\u002Feffect-v4-observability\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: effect-v4-observability\ndescription: Use when adding logging, metrics, tracing\u002Fspans, or OpenTelemetry to Effect v4 code — covers Effect.fn named spans, the Effect.log* family, custom loggers (Logger.make for the format, Logger.withConsoleLog\u002FwithConsoleError for the route — never a hand-written Console.log call), Metric counters\u002Fgauges\u002Fhistograms with Metric.withAttributes (NOT the removed Metric.tagged), and wiring OpenTelemetry export at the app edge (core OTLP layers in effect\u002Fobservability, Tracer.externalSpan and HttpTraceContext for inbound context, HttpClient.TracerPropagationEnabled for outbound, @effect\u002Fopentelemetry only as an optional SDK bridge). Encodes the house rule that pure-tier libraries instrument public fallible boundaries only and stay telemetry-agnostic, while apps compose OTel at the infrastructure layer.\n---\n\n# Effect v4 observability\n\nEvery Effect-core name below was verified to exist against the vendored\nEffect source, and every claimed absence verified absent there.\nCore's own OTLP exporters (`effect\u002Fobservability`) are verified the same way.\n`@effect\u002Fopentelemetry` is **not installed** in this monorepo, so this skill\nnames none of its members; verify any you use against the installed package.\nWhen an API is not listed here, confirm it against the source or a\ntype-checked probe before writing code. Module routing (what\n`Tracer`, `Logger`, `References` are) lives in `effect-v4-module-index`.\n\n## The house rule (this is the whole point)\n\n> Observability is composed **once, at the infrastructure\u002Fedge layer**. Domain\n> operations stay telemetry-agnostic. Libraries never import an exporter —\n> neither `effect\u002Fobservability` nor `@effect\u002Fopentelemetry`.\n\nThe official Effect observability guide endorses this exactly: \"business code\nstays observability-agnostic; OpenTelemetry is introduced at the infrastructure\nlayer, not inside domain operations.\" Our pure-tier libraries (semver, jsonc,\nyaml) are a *specialization* of that guide, not a deviation.\n\n**Our specialization for pure-tier parser\u002Fengine libraries:** instrument\n**public fallible boundaries only** with named `Effect.fn(\"Name.op\")` spans.\n**No per-node \u002F hot-path spans.** No metrics on internal helpers. Apps compose an\nexporter (core's `Otlp` layers) at their edge and get traces\u002Fmetrics\u002Flogs from the\nlibrary for free — because the library only emits named spans at the operations\na user actually calls.\n\n**Coverage is uniform, not selective.** \"Boundaries only\" is a ceiling (don't go\nbelow the public boundary), not a filter for picking the interesting ones. Every\npublic fallible method of a service gets a named span — if one is traced, all of\nthem are. Partial coverage is worse than none: a user tracing their app sees one\nmethod light up but not its equally-public siblings and reasonably concludes\nthose never ran or cannot fail. The blind spot reads as signal.\n\n## Tracing — `Effect.fn` is the v4 idiom\n\n`Effect.fn`, `Effect.fnUntraced`, `Effect.withSpan`, `Effect.withSpanScoped`,\n`Effect.withParentSpan`, `Effect.annotateCurrentSpan`, `Effect.withLogSpan` — all\nstill exported from `Effect.ts`.\n\n```ts\nimport { Effect } from \"effect\"\n\n\u002F\u002F Named span — our default at PUBLIC FALLIBLE boundaries (Yaml.parse, SemVer.parse).\nconst parse = Effect.fn(\"Yaml.parse\")(function* (input: string) {\n  yield* Effect.annotateCurrentSpan({ length: input.length }) \u002F\u002F stable IDs \u002F small values ONLY\n  return yield* runEngine(input)\n})\n\n\u002F\u002F Bare Effect.fn (NO name) — the guide's middle ground: keeps stack frames for\n\u002F\u002F better traces WITHOUT emitting a named span. Use for reusable internal ops\n\u002F\u002F where you want stack-frame ergonomics but not span identity.\nconst normalize = Effect.fn(function* (raw: string) {\n  return raw.trim()\n})\n\n\u002F\u002F fnUntraced — measured hot low-level internals ONLY; throws away observability.\nconst tightHelper = Effect.fnUntraced(function* (x: string) {\n  return x\n})\n```\n\nDraw the line by *purpose*: **named span = tracing identity** (public fallible\nboundary only); **bare `Effect.fn` = stack-frame ergonomics** (fine internally);\n**`fnUntraced` = hot path, no frames**. \"Boundaries only\" governs *named* spans —\nit does not forbid bare `Effect.fn` inside an engine.\n\n**Pure `Result`-returning siblings of a spanned boundary carry no span.** This\nis the kit's **Result-parity rule** — ratified kit-wide policy, not a package\nidiosyncrasy (authoritative statement: the effected repo's\n`formatter-convention.md`, decision 6). Scope test: a public boundary returning\n`Effect` with `R = never`, no async step and no IO — where the wrapper carries\nnothing but a span and the error channel — must expose the sync form as the\nprimitive, spelled `*Result` (`Fmt.parseResult` pure, `Fmt.parse` spanned).\nNever `*Sync`: the Effect form is also synchronous, and the kit uses `*Sync`\nfor genuinely-blocking-IO facades returning nullables. Interface\u002Fadapter seams\nare out of scope — the policy applies to the engine, not every adapter over it\n(a codec implementing an `Effect`-shaped interface stays as it is). The sync\nvariant is not an Effect and gets no span, no log, no metric; do not wrap it\nin one to \"keep coverage uniform\" — the uniform-coverage rule governs the\n*Effect* surface. Two obligations instead: the Effect variant is defined **in\nterms of** the Result variant behind its named span (so tracing sees every\nEffect-path call and the two can never diverge), and the sync variant's TSDoc\npoints Effect consumers at the spanned variant. A sync twin whose Effect\nsibling lacks a span, or that quietly grows its own logging, is a review\nfinding — as is an in-scope boundary with no `*Result` twin at all.\n\nExplicit \u002F nested \u002F edge spans:\n\n```ts\nconst sync = Effect.fn(\"User.sync\")(function* (id: string) {\n  const p = yield* fetchProfile(id).pipe(Effect.withSpan(\"fetchProfile\"))\n  return yield* persist(p).pipe(Effect.withSpan(\"persist\"))\n})\n\u002F\u002F withSpanScoped   → span open for a Scope's lifetime (resource \u002F streaming ops)\n\u002F\u002F withParentSpan   → continue an externally-created parent span (framework edge only)\n\u002F\u002F annotateCurrentSpan({ key }) → stable IDs \u002F small structured values; never\n\u002F\u002F                    giant payloads, secrets, or noisy transient data\n```\n\n## Structured logging\n\n`Effect.log`, `logTrace`, `logDebug`, `logInfo`, `logWarning`, `logError`,\n`logFatal`, `annotateLogs` — all still exported. They flow through the\ncurrent fiber: span context, annotations, and log spans attach automatically.\n\n```ts\nyield* Effect.logInfo(\"starting sync\", { userId })   \u002F\u002F structured 2nd arg — verified\n\u002F\u002F Logical label without a full tracing span:\nconst program = Effect.logInfo(\"starting sync\").pipe(Effect.withLogSpan(\"user-sync\"))\n```\n\nGuide rules: log at business boundaries, not every helper; structured values over\nconcatenated strings; high-signal only; no duplicate logs at every layer. Rely on\nspans plus a few well-placed logs. For libraries this means: don't scatter logs\nthrough the engine — a public boundary may log, the hot path does not.\n\n### Custom loggers — format with `Logger.make`, route with `withConsoleLog`\n\nA `Logger\u003CMessage, Output>` is one method, `log(options): Output` (`Logger.ts:66`).\nKeep **formatting** and **routing** as two loggers, because core already ships\nthe routing half:\n\n```ts\nconst format = Logger.make((o) => `${o.logLevel}: ${String(o.message)}`)   \u002F\u002F Logger\u003Cunknown, string>\nconst toStdout = Logger.withConsoleLog(format)                            \u002F\u002F Logger\u003Cunknown, void>\nconst toStderr = Logger.withConsoleError(format)\nprogram.pipe(Effect.provide(Logger.layer([toStdout])))\n```\n\n`Logger.withConsoleLog` \u002F `withConsoleError` (`Logger.ts:273,314`) read the\n`Console` service off the fiber and call `console.log` \u002F `console.error` with\n`self.log(options)` — which is also how you **reuse a logger inside another**:\ncall `inner.log(options)`, never re-render. The trap is writing that routing\nline by hand — `Logger.make((o) => o.fiber.getRef(Console.Console).log(render(o)))`\n— which duplicates core and drifts from it (two such sites had accreted in\n`github-actions` before #769). The built-ins are the same composition:\n`consoleLogFmt` \u002F `consoleStructured` \u002F `consoleJson` are\n`withConsoleLog(formatLogFmt | formatStructured | formatJson)` (`Logger.ts:942-992`),\nand `Logger.map(logger, f)` post-processes an output. Because the route goes\nthrough the `Console` service, `TestConsole` captures it: probed,\n`Effect.logInfo(\"hello\")` under `Logger.layer([withConsoleLog(format)])` lands\nin `TestConsole.logLines` as `[\"Info: hello\"]` and the `withConsoleError` twin in\n`errorLines` — the `ConsoleRef` coupling `effect-v4-testing` warns about is the\nsame mechanism, and here it works for you.\n\n## Metrics\n\nThe `Metric` surface: `counter`, `gauge`, `histogram`, `frequency`,\n`summary`, `timer`, `withAttributes`, `withConstantInput`, `linearBoundaries`,\n`exponentialBoundaries`, `boundariesFromIterable` — all exported from\n`Metric.ts`.\n\n```ts\nimport { Effect, Metric } from \"effect\"\n\nconst requests = Metric.counter(\"user_load_requests\").pipe(\n  Metric.withConstantInput(1)\n)\n\n\u002F\u002F Attach a metric at a boundary via Effect.track — the post-processing arg to\n\u002F\u002F Effect.fn. Verified: Effect.fn(\"name\")(gen, Effect.track(metric)) typechecks and runs.\nconst loadUser = Effect.fn(\"loadUser\")(\n  function* (userId: string) {\n    return { id: userId }\n  },\n  Effect.track(requests)\n)\n```\n\n**Names that are easy to reach for and do not exist** (each absence verified\nabsent in the source):\n\n- There is no `Metric.tagged` \u002F `Metric.taggedWithLabels`. Use\n  `Metric.withAttributes({ ... })`; ambient attributes ride on\n  `Metric.CurrentMetricAttributes` (`Metric.ts:1623`) — a **`Context.Reference`**,\n  and there is no `FiberRef`, so read and scope it the way `effect-v4-idioms`\n  describes for any reference: `yield*` it to read, `Effect.provideService` to\n  scope a value.\n- Histogram boundaries: `Metric.linearBoundaries`, `Metric.exponentialBoundaries`,\n  `Metric.boundariesFromIterable` — there is no `MetricBoundaries.*` module on the\n  `Metric` surface. `Metric.timer` exists; `timerWithBoundaries` does not.\n- `Effect.track` bolts a metric onto an effect \u002F `Effect.fn`.\n\nGuide rule: metrics belong on **boundaries** — endpoint\u002Fqueue\u002Fjob handlers,\nrepository ops, external-API calls, retries — never on every internal helper. For\npure-tier libraries the honest default is **no metrics at all**; let the app meter\nits call to the library.\n\n## OpenTelemetry — at the app edge only\n\nLibraries never touch this. An **application** composes one telemetry layer at\nits top level.\n\n### Core OTLP export (`effect\u002Fobservability`)\n\nCore ships vendor-neutral OTLP exporters, so most apps need no SDK at all.\n`Otlp.layer` installs the OTLP logger, metrics exporter and tracer exporter from\none configuration, posting to `\u002Fv1\u002Flogs`, `\u002Fv1\u002Fmetrics` and `\u002Fv1\u002Ftraces` under\n`baseUrl`. It needs an `HttpClient`, and an `OtlpSerialization` that\n`layerJson` \u002F `layerProtobuf` already provide:\n\n```ts\nimport { Layer } from \"effect\"\nimport { FetchHttpClient } from \"effect\u002Fhttp\"\nimport { Otlp, OtlpSerialization } from \"effect\u002Fobservability\"\n\n\u002F\u002F Explicit endpoint, JSON encoding.\nconst TelemetryLayer = Otlp.layerJson({\n  baseUrl: \"http:\u002F\u002Flocalhost:4318\",\n  resource: { serviceName: \"todo-service\", serviceVersion: \"1.0.0\" }\n}).pipe(Layer.provide(FetchHttpClient.layer))\n\n\u002F\u002F Or from the standard OTEL_* environment (OTEL_SDK_DISABLED, OTEL_EXPORTER_OTLP_*,\n\u002F\u002F OTEL_\u003CSIGNAL>_EXPORTER, OTEL_BSP_*); this form takes the serialization explicitly.\n\u002F\u002F It exports nothing until OTEL_\u003CSIGNAL>_EXPORTER includes `otlp` (see below).\nconst TelemetryFromEnv = Otlp.layerFromConfig({ resource: { serviceName: \"todo-service\" } }).pipe(\n  Layer.provide(OtlpSerialization.layerJson),\n  Layer.provide(FetchHttpClient.layer)\n)\n\nconst AppLayer = Layer.mergeAll(DomainLayer, HttpLayer).pipe(Layer.provide(TelemetryLayer))\n```\n\n- `layer` \u002F `layerJson` \u002F `layerProtobuf` \u002F `layerFromConfig` are the four\n  entry points; the per-signal modules (`OtlpTracer`, `OtlpLogger`,\n  `OtlpMetrics`) exist for an app exporting only one signal.\n- **`layerFromConfig` is gated by the environment, per signal.**\n  `Otlp.layerFromConfig` and `OtlpMetrics.layerFromConfig` (and the tracer and\n  logger equivalents) export nothing — the layer installs only a flusher, and\n  flushing is a no-op — unless `OTEL_\u003CSIGNAL>_EXPORTER` (`OTEL_TRACES_EXPORTER`,\n  `OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER`) includes `otlp` **and** an\n  endpoint is set; `OTEL_SDK_DISABLED=true` also disables it. An unset\n  `OTEL_\u003CSIGNAL>_EXPORTER` counts as an empty list, so set it explicitly. A\n  configuration error in these layers is a defect (`Effect.orDie`), not a typed\n  failure. The explicit `layer` \u002F `layerJson` \u002F `layerProtobuf` forms take their\n  options directly and have no exporter gate.\n- Default export intervals differ by signal: traces 5 s, logs 1 s, metrics\n  10 s. Override with `tracerExportInterval`, `loggerExportInterval` and\n  `metricsExportInterval` on `Otlp.layer` \u002F `layerJson` \u002F `layerProtobuf` (the\n  per-signal modules take plain `exportInterval`); `layerFromConfig`\n  reads `OTEL_BSP_SCHEDULE_DELAY` (traces), `OTEL_BLRP_SCHEDULE_DELAY` (logs) and\n  `OTEL_METRIC_EXPORT_INTERVAL` (metrics).\n- **Request URLs reach exported spans.** Whenever a tracer is live, `effect\u002Fhttp`'s\n  `HttpClient` records `url.full`, `url.path` and `url.query` on each request\n  span, and the OTLP tracer ships them off the machine. Only the names in\n  `UrlParams.CurrentRedactedNames` are redacted by default (the signed-URL\n  names `X-Amz-Signature`, `X-Amz-Credential`, `X-Amz-Security-Token`,\n  `AWSAccessKeyId`, `Signature`, `sig`, `X-Goog-Signature`), so a `?token=`\n  query value is exported as written. `url.path` is never redacted, so a secret\n  in the path goes out as written too. Extend the list by providing\n  `UrlParams.CurrentRedactedNames`; a custom list replaces the defaults.\n  For names secret only in one `HttpApi`, annotate the API, group or endpoint\n  with `HttpApi.RedactedNames` instead: `HttpApiBuilder` and `HttpApiClient`\n  add those query and header names to the global lists in their spans. A scoped\n  `CurrentRedactedNames` set inside a handler never reaches the server span,\n  which is recorded after the handler's context is restored.\n  The exporter's own posts are not traced.\n- The layers own export batching and shutdown (`shutdownTimeout`) — **never\n  flush or shut an exporter down from business code.**\n\n### Bridging trace context\n\n- **Inbound**, at the HTTP\u002FRPC\u002Fqueue adapter only: `HttpTraceContext.fromHeaders`\n  (`effect\u002Fhttp`) reads `traceparent`\u002F`b3` into an `Option\u003CTracer.ExternalSpan>`;\n  for any other carrier build one with `Tracer.externalSpan({ spanId, traceId })`.\n  Parent the handler on it with `Effect.withSpan(name, { parent })` or\n  `Effect.withParentSpan(span)`.\n- **Outbound**, core's `HttpClient` writes `b3` and `traceparent` on every\n  request by default. That is right inside your own system and wrong toward a\n  third party, which then receives your trace and span ids. Turn it off per\n  client with the `HttpClient.TracerPropagationEnabled` reference; the client\n  span is still recorded locally:\n\n  ```ts\n  const http = HttpClient.transform(yield* HttpClient.HttpClient, (effect) =>\n    Effect.provideService(effect, HttpClient.TracerPropagationEnabled, false)\n  )\n  ```\n\n  The kit's example is `@effected\u002Fgithub-actions`' S3 `BlobStore`, which signs\n  requests to a third-party object store and sends it no trace context.\n\n### `@effect\u002Fopentelemetry` (optional SDK bridge)\n\nReach for it only when the app must run the OpenTelemetry JS SDK itself (its\nspan processors, an exporter core does not ship, or another library already\ninstrumented through the SDK). It is not vendored in this kit, so **verify\nevery name against the installed package** before writing it; do not take one\nfrom memory or from older guides.\n\n**Anti-patterns:** constructing OTel SDK clients inside services; wiring\nexporters in domain code; scattering shutdown logic; per-subsystem telemetry\nconfig instead of one top-level layer; propagating trace headers to a\nthird-party API.\n\n## How to verify quickly\n\n```bash\ncd packages\u002Fyaml && node --input-type=module -e \"\nimport * as Metric from 'effect\u002FMetric';\nconsole.log(typeof Metric.withAttributes, typeof Metric.tagged);\n\"   # → function undefined\n```\n\nOne runtime probe beats an hour of guessing whether a name exists.\n","# Effect v4 observability\n\nEvery Effect-core name below was verified to exist against the vendored\nEffect source, and every claimed absence verified absent there.\nCore's own OTLP exporters (`effect\u002Fobservability`) are verified the same way.\n`@effect\u002Fopentelemetry` is **not installed** in this monorepo, so this skill\nnames none of its members; verify any you use against the installed package.\nWhen an API is not listed here, confirm it against the source or a\ntype-checked probe before writing code. Module routing (what\n`Tracer`, `Logger`, `References` are) lives in `effect-v4-module-index`.\n\n## The house rule (this is the whole point)\n\n> Observability is composed **once, at the infrastructure\u002Fedge layer**. Domain\n> operations stay telemetry-agnostic. Libraries never import an exporter —\n> neither `effect\u002Fobservability` nor `@effect\u002Fopentelemetry`.\n\nThe official Effect observability guide endorses this exactly: \"business code\nstays observability-agnostic; OpenTelemetry is introduced at the infrastructure\nlayer, not inside domain operations.\" Our pure-tier libraries (semver, jsonc,\nyaml) are a *specialization* of that guide, not a deviation.\n\n**Our specialization for pure-tier parser\u002Fengine libraries:** instrument\n**public fallible boundaries only** with named `Effect.fn(\"Name.op\")` spans.\n**No per-node \u002F hot-path spans.** No metrics on internal helpers. Apps compose an\nexporter (core's `Otlp` layers) at their edge and get traces\u002Fmetrics\u002Flogs from the\nlibrary for free — because the library only emits named spans at the operations\na user actually calls.\n\n**Coverage is uniform, not selective.** \"Boundaries only\" is a ceiling (don't go\nbelow the public boundary), not a filter for picking the interesting ones. Every\npublic fallible method of a service gets a named span — if one is traced, all of\nthem are. Partial coverage is worse than none: a user tracing their app sees one\nmethod light up but not its equally-public siblings and reasonably concludes\nthose never ran or cannot fail. The blind spot reads as signal.\n\n## Tracing — `Effect.fn` is the v4 idiom\n\n`Effect.fn`, `Effect.fnUntraced`, `Effect.withSpan`, `Effect.withSpanScoped`,\n`Effect.withParentSpan`, `Effect.annotateCurrentSpan`, `Effect.withLogSpan` — all\nstill exported from `Effect.ts`.\n\n```ts\nimport { Effect } from \"effect\"\n\n\u002F\u002F Named span — our default at PUBLIC FALLIBLE boundaries (Yaml.parse, SemVer.parse).\nconst parse = Effect.fn(\"Yaml.parse\")(function* (input: string) {\n  yield* Effect.annotateCurrentSpan({ length: input.length }) \u002F\u002F stable IDs \u002F small values ONLY\n  return yield* runEngine(input)\n})\n\n\u002F\u002F Bare Effect.fn (NO name) — the guide's middle ground: keeps stack frames for\n\u002F\u002F better traces WITHOUT emitting a named span. Use for reusable internal ops\n\u002F\u002F where you want stack-frame ergonomics but not span identity.\nconst normalize = Effect.fn(function* (raw: string) {\n  return raw.trim()\n})\n\n\u002F\u002F fnUntraced — measured hot low-level internals ONLY; throws away observability.\nconst tightHelper = Effect.fnUntraced(function* (x: string) {\n  return x\n})\n```\n\nDraw the line by *purpose*: **named span = tracing identity** (public fallible\nboundary only); **bare `Effect.fn` = stack-frame ergonomics** (fine internally);\n**`fnUntraced` = hot path, no frames**. \"Boundaries only\" governs *named* spans —\nit does not forbid bare `Effect.fn` inside an engine.\n\n**Pure `Result`-returning siblings of a spanned boundary carry no span.** This\nis the kit's **Result-parity rule** — ratified kit-wide policy, not a package\nidiosyncrasy (authoritative statement: the effected repo's\n`formatter-convention.md`, decision 6). Scope test: a public boundary returning\n`Effect` with `R = never`, no async step and no IO — where the wrapper carries\nnothing but a span and the error channel — must expose the sync form as the\nprimitive, spelled `*Result` (`Fmt.parseResult` pure, `Fmt.parse` spanned).\nNever `*Sync`: the Effect form is also synchronous, and the kit uses `*Sync`\nfor genuinely-blocking-IO facades returning nullables. Interface\u002Fadapter seams\nare out of scope — the policy applies to the engine, not every adapter over it\n(a codec implementing an `Effect`-shaped interface stays as it is). The sync\nvariant is not an Effect and gets no span, no log, no metric; do not wrap it\nin one to \"keep coverage uniform\" — the uniform-coverage rule governs the\n*Effect* surface. Two obligations instead: the Effect variant is defined **in\nterms of** the Result variant behind its named span (so tracing sees every\nEffect-path call and the two can never diverge), and the sync variant's TSDoc\npoints Effect consumers at the spanned variant. A sync twin whose Effect\nsibling lacks a span, or that quietly grows its own logging, is a review\nfinding — as is an in-scope boundary with no `*Result` twin at all.\n\nExplicit \u002F nested \u002F edge spans:\n\n```ts\nconst sync = Effect.fn(\"User.sync\")(function* (id: string) {\n  const p = yield* fetchProfile(id).pipe(Effect.withSpan(\"fetchProfile\"))\n  return yield* persist(p).pipe(Effect.withSpan(\"persist\"))\n})\n\u002F\u002F withSpanScoped   → span open for a Scope's lifetime (resource \u002F streaming ops)\n\u002F\u002F withParentSpan   → continue an externally-created parent span (framework edge only)\n\u002F\u002F annotateCurrentSpan({ key }) → stable IDs \u002F small structured values; never\n\u002F\u002F                    giant payloads, secrets, or noisy transient data\n```\n\n## Structured logging\n\n`Effect.log`, `logTrace`, `logDebug`, `logInfo`, `logWarning`, `logError`,\n`logFatal`, `annotateLogs` — all still exported. They flow through the\ncurrent fiber: span context, annotations, and log spans attach automatically.\n\n```ts\nyield* Effect.logInfo(\"starting sync\", { userId })   \u002F\u002F structured 2nd arg — verified\n\u002F\u002F Logical label without a full tracing span:\nconst program = Effect.logInfo(\"starting sync\").pipe(Effect.withLogSpan(\"user-sync\"))\n```\n\nGuide rules: log at business boundaries, not every helper; structured values over\nconcatenated strings; high-signal only; no duplicate logs at every layer. Rely on\nspans plus a few well-placed logs. For libraries this means: don't scatter logs\nthrough the engine — a public boundary may log, the hot path does not.\n\n### Custom loggers — format with `Logger.make`, route with `withConsoleLog`\n\nA `Logger\u003CMessage, Output>` is one method, `log(options): Output` (`Logger.ts:66`).\nKeep **formatting** and **routing** as two loggers, because core already ships\nthe routing half:\n\n```ts\nconst format = Logger.make((o) => `${o.logLevel}: ${String(o.message)}`)   \u002F\u002F Logger\u003Cunknown, string>\nconst toStdout = Logger.withConsoleLog(format)                            \u002F\u002F Logger\u003Cunknown, void>\nconst toStderr = Logger.withConsoleError(format)\nprogram.pipe(Effect.provide(Logger.layer([toStdout])))\n```\n\n`Logger.withConsoleLog` \u002F `withConsoleError` (`Logger.ts:273,314`) read the\n`Console` service off the fiber and call `console.log` \u002F `console.error` with\n`self.log(options)` — which is also how you **reuse a logger inside another**:\ncall `inner.log(options)`, never re-render. The trap is writing that routing\nline by hand — `Logger.make((o) => o.fiber.getRef(Console.Console).log(render(o)))`\n— which duplicates core and drifts from it (two such sites had accreted in\n`github-actions` before #769). The built-ins are the same composition:\n`consoleLogFmt` \u002F `consoleStructured` \u002F `consoleJson` are\n`withConsoleLog(formatLogFmt | formatStructured | formatJson)` (`Logger.ts:942-992`),\nand `Logger.map(logger, f)` post-processes an output. Because the route goes\nthrough the `Console` service, `TestConsole` captures it: probed,\n`Effect.logInfo(\"hello\")` under `Logger.layer([withConsoleLog(format)])` lands\nin `TestConsole.logLines` as `[\"Info: hello\"]` and the `withConsoleError` twin in\n`errorLines` — the `ConsoleRef` coupling `effect-v4-testing` warns about is the\nsame mechanism, and here it works for you.\n\n## Metrics\n\nThe `Metric` surface: `counter`, `gauge`, `histogram`, `frequency`,\n`summary`, `timer`, `withAttributes`, `withConstantInput`, `linearBoundaries`,\n`exponentialBoundaries`, `boundariesFromIterable` — all exported from\n`Metric.ts`.\n\n```ts\nimport { Effect, Metric } from \"effect\"\n\nconst requests = Metric.counter(\"user_load_requests\").pipe(\n  Metric.withConstantInput(1)\n)\n\n\u002F\u002F Attach a metric at a boundary via Effect.track — the post-processing arg to\n\u002F\u002F Effect.fn. Verified: Effect.fn(\"name\")(gen, Effect.track(metric)) typechecks and runs.\nconst loadUser = Effect.fn(\"loadUser\")(\n  function* (userId: string) {\n    return { id: userId }\n  },\n  Effect.track(requests)\n)\n```\n\n**Names that are easy to reach for and do not exist** (each absence verified\nabsent in the source):\n\n- There is no `Metric.tagged` \u002F `Metric.taggedWithLabels`. Use\n  `Metric.withAttributes({ ... })`; ambient attributes ride on\n  `Metric.CurrentMetricAttributes` (`Metric.ts:1623`) — a **`Context.Reference`**,\n  and there is no `FiberRef`, so read and scope it the way `effect-v4-idioms`\n  describes for any reference: `yield*` it to read, `Effect.provideService` to\n  scope a value.\n- Histogram boundaries: `Metric.linearBoundaries`, `Metric.exponentialBoundaries`,\n  `Metric.boundariesFromIterable` — there is no `MetricBoundaries.*` module on the\n  `Metric` surface. `Metric.timer` exists; `timerWithBoundaries` does not.\n- `Effect.track` bolts a metric onto an effect \u002F `Effect.fn`.\n\nGuide rule: metrics belong on **boundaries** — endpoint\u002Fqueue\u002Fjob handlers,\nrepository ops, external-API calls, retries — never on every internal helper. For\npure-tier libraries the honest default is **no metrics at all**; let the app meter\nits call to the library.\n\n## OpenTelemetry — at the app edge only\n\nLibraries never touch this. An **application** composes one telemetry layer at\nits top level.\n\n### Core OTLP export (`effect\u002Fobservability`)\n\nCore ships vendor-neutral OTLP exporters, so most apps need no SDK at all.\n`Otlp.layer` installs the OTLP logger, metrics exporter and tracer exporter from\none configuration, posting to `\u002Fv1\u002Flogs`, `\u002Fv1\u002Fmetrics` and `\u002Fv1\u002Ftraces` under\n`baseUrl`. It needs an `HttpClient`, and an `OtlpSerialization` that\n`layerJson` \u002F `layerProtobuf` already provide:\n\n```ts\nimport { Layer } from \"effect\"\nimport { FetchHttpClient } from \"effect\u002Fhttp\"\nimport { Otlp, OtlpSerialization } from \"effect\u002Fobservability\"\n\n\u002F\u002F Explicit endpoint, JSON encoding.\nconst TelemetryLayer = Otlp.layerJson({\n  baseUrl: \"http:\u002F\u002Flocalhost:4318\",\n  resource: { serviceName: \"todo-service\", serviceVersion: \"1.0.0\" }\n}).pipe(Layer.provide(FetchHttpClient.layer))\n\n\u002F\u002F Or from the standard OTEL_* environment (OTEL_SDK_DISABLED, OTEL_EXPORTER_OTLP_*,\n\u002F\u002F OTEL_\u003CSIGNAL>_EXPORTER, OTEL_BSP_*); this form takes the serialization explicitly.\n\u002F\u002F It exports nothing until OTEL_\u003CSIGNAL>_EXPORTER includes `otlp` (see below).\nconst TelemetryFromEnv = Otlp.layerFromConfig({ resource: { serviceName: \"todo-service\" } }).pipe(\n  Layer.provide(OtlpSerialization.layerJson),\n  Layer.provide(FetchHttpClient.layer)\n)\n\nconst AppLayer = Layer.mergeAll(DomainLayer, HttpLayer).pipe(Layer.provide(TelemetryLayer))\n```\n\n- `layer` \u002F `layerJson` \u002F `layerProtobuf` \u002F `layerFromConfig` are the four\n  entry points; the per-signal modules (`OtlpTracer`, `OtlpLogger`,\n  `OtlpMetrics`) exist for an app exporting only one signal.\n- **`layerFromConfig` is gated by the environment, per signal.**\n  `Otlp.layerFromConfig` and `OtlpMetrics.layerFromConfig` (and the tracer and\n  logger equivalents) export nothing — the layer installs only a flusher, and\n  flushing is a no-op — unless `OTEL_\u003CSIGNAL>_EXPORTER` (`OTEL_TRACES_EXPORTER`,\n  `OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER`) includes `otlp` **and** an\n  endpoint is set; `OTEL_SDK_DISABLED=true` also disables it. An unset\n  `OTEL_\u003CSIGNAL>_EXPORTER` counts as an empty list, so set it explicitly. A\n  configuration error in these layers is a defect (`Effect.orDie`), not a typed\n  failure. The explicit `layer` \u002F `layerJson` \u002F `layerProtobuf` forms take their\n  options directly and have no exporter gate.\n- Default export intervals differ by signal: traces 5 s, logs 1 s, metrics\n  10 s. Override with `tracerExportInterval`, `loggerExportInterval` and\n  `metricsExportInterval` on `Otlp.layer` \u002F `layerJson` \u002F `layerProtobuf` (the\n  per-signal modules take plain `exportInterval`); `layerFromConfig`\n  reads `OTEL_BSP_SCHEDULE_DELAY` (traces), `OTEL_BLRP_SCHEDULE_DELAY` (logs) and\n  `OTEL_METRIC_EXPORT_INTERVAL` (metrics).\n- **Request URLs reach exported spans.** Whenever a tracer is live, `effect\u002Fhttp`'s\n  `HttpClient` records `url.full`, `url.path` and `url.query` on each request\n  span, and the OTLP tracer ships them off the machine. Only the names in\n  `UrlParams.CurrentRedactedNames` are redacted by default (the signed-URL\n  names `X-Amz-Signature`, `X-Amz-Credential`, `X-Amz-Security-Token`,\n  `AWSAccessKeyId`, `Signature`, `sig`, `X-Goog-Signature`), so a `?token=`\n  query value is exported as written. `url.path` is never redacted, so a secret\n  in the path goes out as written too. Extend the list by providing\n  `UrlParams.CurrentRedactedNames`; a custom list replaces the defaults.\n  For names secret only in one `HttpApi`, annotate the API, group or endpoint\n  with `HttpApi.RedactedNames` instead: `HttpApiBuilder` and `HttpApiClient`\n  add those query and header names to the global lists in their spans. A scoped\n  `CurrentRedactedNames` set inside a handler never reaches the server span,\n  which is recorded after the handler's context is restored.\n  The exporter's own posts are not traced.\n- The layers own export batching and shutdown (`shutdownTimeout`) — **never\n  flush or shut an exporter down from business code.**\n\n### Bridging trace context\n\n- **Inbound**, at the HTTP\u002FRPC\u002Fqueue adapter only: `HttpTraceContext.fromHeaders`\n  (`effect\u002Fhttp`) reads `traceparent`\u002F`b3` into an `Option\u003CTracer.ExternalSpan>`;\n  for any other carrier build one with `Tracer.externalSpan({ spanId, traceId })`.\n  Parent the handler on it with `Effect.withSpan(name, { parent })` or\n  `Effect.withParentSpan(span)`.\n- **Outbound**, core's `HttpClient` writes `b3` and `traceparent` on every\n  request by default. That is right inside your own system and wrong toward a\n  third party, which then receives your trace and span ids. Turn it off per\n  client with the `HttpClient.TracerPropagationEnabled` reference; the client\n  span is still recorded locally:\n\n  ```ts\n  const http = HttpClient.transform(yield* HttpClient.HttpClient, (effect) =>\n    Effect.provideService(effect, HttpClient.TracerPropagationEnabled, false)\n  )\n  ```\n\n  The kit's example is `@effected\u002Fgithub-actions`' S3 `BlobStore`, which signs\n  requests to a third-party object store and sends it no trace context.\n\n### `@effect\u002Fopentelemetry` (optional SDK bridge)\n\nReach for it only when the app must run the OpenTelemetry JS SDK itself (its\nspan processors, an exporter core does not ship, or another library already\ninstrumented through the SDK). It is not vendored in this kit, so **verify\nevery name against the installed package** before writing it; do not take one\nfrom memory or from older guides.\n\n**Anti-patterns:** constructing OTel SDK clients inside services; wiring\nexporters in domain code; scattering shutdown logic; per-subsystem telemetry\nconfig instead of one top-level layer; propagating trace headers to a\nthird-party API.\n\n## How to verify quickly\n\n```bash\ncd packages\u002Fyaml && node --input-type=module -e \"\nimport * as Metric from 'effect\u002FMetric';\nconsole.log(typeof Metric.withAttributes, typeof Metric.tagged);\n\"   # → function undefined\n```\n\nOne runtime probe beats an hour of guessing whether a name exists.\n",{"name":5,"description":7},"main","3beb0433e15650b598c22b7b7299eb6fa411b9b4","plugin\u002Fbuilds\u002Fcopilot\u002Fskills\u002Feffect-v4-observability",2,"https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected","https:\u002F\u002Fgithub.com\u002Fspencerbeggs","2026-11-14 07:03:25",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add spencerbeggs\u002Feffected --skill effect-v4-observability",{"tool":37,"command":38},"bunx","bunx skills add spencerbeggs\u002Feffected --skill effect-v4-observability",{"tool":40,"command":41},"pnpm","pnpm dlx skills add spencerbeggs\u002Feffected --skill effect-v4-observability","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fbuilds\u002Fcopilot\u002Fskills\u002Feffect-v4-observability\u002FSKILL.md",true,[],[46,53,60,67,74,81],{"skillNo":47,"name":48,"nameZh":6,"description":49,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":50,"categories":51,"keywords":52,"publishedAt":19},"01M780NVTD800KMFV869YNZED6","testing-actions","Use when writing or reviewing tests for @effected\u002Fgithub-actions, @effected\u002Fgithub, @effected\u002Fsbom or @effected\u002Fcommands — stubbing the GitHub API, writing a service's layerTest or makeTest double, testing the pre\u002Fmain\u002Fpost lifecycle through Action.run, or debugging why a test hits the real network or hangs.","https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fskills\u002Ftesting-actions\u002FSKILL.md",[],[],{"skillNo":54,"name":55,"nameZh":6,"description":56,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":57,"categories":58,"keywords":59,"publishedAt":19},"01M780NPDSGFC0FCP7696NW11J","supply-chain-attestation","Use when generating a CycloneDX SBOM, checking NTIA minimum elements, building an in-toto statement or a SLSA provenance predicate, signing into a Sigstore DSSE bundle, or uploading an attestation to GitHub.","https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fskills\u002Fsupply-chain-attestation\u002FSKILL.md",[],[],{"skillNo":61,"name":62,"nameZh":6,"description":63,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":64,"categories":65,"keywords":66,"publishedAt":19},"01M780NGP4QNZDH8T8Q8WZ18SA","structuring-an-action","Use when laying out a new GitHub Action repository on the @effected suite, deciding where a piece of code belongs (an entry point, a step, a shared service, a shim), or reviewing an existing action's file structure against the canonical shape.","https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fskills\u002Fstructuring-an-action\u002FSKILL.md",[],[],{"skillNo":68,"name":69,"nameZh":6,"description":70,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":71,"categories":72,"keywords":73,"publishedAt":19},"01M780NCD52H1Y03FS83WJ8BT5","running-commands-and-tools","Use when running a subprocess in Effect v4, spawning a command, capturing stdout\u002Fstderr\u002Fexit code, checking whether a CLI tool is installed or which copy to run, running a package-manager script through the project's launcher, detaching a background process, or redacting a secret from argv or captured output.","https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fskills\u002Frunning-commands-and-tools\u002FSKILL.md",[],[],{"skillNo":75,"name":76,"nameZh":6,"description":77,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":78,"categories":79,"keywords":80,"publishedAt":19},"01M780N823DWNRMSY5X2NT5MSR","release-and-publish","Use when publishing a package to npm, reading the npm registry from Effect v4, checking whether a version is already published, cutting a release tag or GitHub release from an action, applying a release-age gate, or deriving tracking tags for GitHub Actions distribution.","https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fskills\u002Frelease-and-publish\u002FSKILL.md",[],[],{"skillNo":82,"name":83,"nameZh":6,"description":84,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":19},"01M780MXRF6H20KCESTSSFB3HQ","hardening-a-parser-port","Use when porting or writing a recursive-descent parser, lexer, or tree-walker over untrusted text in the @effected monorepo — the class of hardening the cloud reviewer scans for on every migration. Covers stack-overflow depth guards (on EVERY recursion surface, which a facade has N of — not two), numeric bound guards that must reject NaN and non-integers, code-point range checks scoped to formats with wide escapes, prototype-pollution, control-character rejection, and the invariant that malformed input must fail through the typed error channel, never as an unhandled defect.","https:\u002F\u002Fgithub.com\u002Fspencerbeggs\u002Feffected\u002Fblob\u002Fmain\u002Fplugin\u002Fskills\u002Fhardening-a-parser-port\u002FSKILL.md",[],[]]