effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/unstable/httpapi/index.ts

@@ -5,377 +5,66 @@
 // @barrel: Auto-generated exports. Do not edit manually.
 
 /**
- * The `HttpApi` module defines the top-level contract for an Effect HTTP API.
- * An `HttpApi` names an API and collects one or more `HttpApiGroup`s, whose
- * endpoints describe the request inputs, response schemas, middleware, and
- * annotations that later drive server builders, clients, and OpenAPI
- * generation.
- *
- * Use this module when you want to compose a domain API from endpoint groups,
- * combine APIs from multiple modules, apply a shared path prefix or middleware,
- * attach annotations, or reflect over the final route shape. Implementations are
- * provided separately with `HttpApiBuilder.group`, and the completed API is
- * registered with `HttpApiBuilder.layer`.
- *
- * A few composition details are worth keeping in mind: group identifiers are
- * used as keys, so adding another group with the same identifier replaces the
- * previous one; `prefix` and `middleware` are applied to the groups and
- * endpoints already present when they are called; and `addHttpApi` merges the
- * added API's annotations into its groups. During reflection, success and error
- * schemas are grouped by the HTTP status recorded on their `HttpApiSchema`
- * annotations, endpoints without an explicit success schema default to
- * `NoContent`, and middleware error schemas are included with endpoint errors.
- * Extra schemas supplied through `AdditionalSchemas` must have an `identifier`
- * annotation so they can be emitted as OpenAPI components.
- *
  * @since 4.0.0
  */
 export * as HttpApi from "./HttpApi.ts"
 
 /**
- * The `HttpApiBuilder` module connects declarative `HttpApi` definitions to
- * runnable HTTP server routes.
- *
- * Use this module when you have described an API with `HttpApi`,
- * `HttpApiGroup`, and `HttpApiEndpoint` values and need to provide the
- * server-side implementation. `group` creates a layer for implementing every
- * endpoint in one API group, `layer` registers the implemented groups with an
- * `HttpRouter` and can expose the generated OpenAPI specification, and
- * `endpoint` builds the effect for a single endpoint when custom composition is
- * needed.
- *
- * The builder performs the runtime work implied by endpoint metadata: it decodes
- * path parameters, headers, query parameters, and request payloads with
- * `Schema`, applies endpoint middleware and security middleware, invokes the
- * registered handler, and encodes successful or declared error results into
- * `HttpServerResponse` values. Handlers can return an `HttpServerResponse`
- * directly to bypass success encoding, and `handleRaw` can be used when payload
- * decoding should be handled manually.
- *
- * A few implementation details are worth keeping in mind. Every group in the
- * API must be provided with `HttpApiBuilder.group` before `layer` is evaluated,
- * otherwise registration fails with a defect that names the missing group and
- * the available group services. Payload decoding is selected by request media type;
- * unsupported content types produce a `415` response before the handler runs.
- * Schema failures are wrapped as `HttpApiSchemaError`, while ordinary handler
- * failures are encoded with the endpoint's declared error schemas.
- *
  * @since 4.0.0
  */
 export * as HttpApiBuilder from "./HttpApiBuilder.ts"
 
 /**
- * Builds type-safe clients and URL builders from `HttpApi` declarations.
- *
- * This module turns the groups and endpoints described by an `HttpApi` into
- * callable client methods backed by an `HttpClient`. Applications commonly use
- * `make` or `makeWith` to call a remote API with the same schema-driven contract
- * as the server, while `group`, `endpoint`, and `urlBuilder` are useful when only
- * part of an API or only the encoded URL is needed.
- *
- * Client calls encode path parameters, query values, headers, and payloads from
- * endpoint schemas before executing the request, then decode successful responses
- * according to the endpoint success schemas. The selected `responseMode` can
- * return the decoded value, the raw `HttpClientResponse`, or both; the raw
- * response mode skips success and error decoding for custom response handling.
- *
- * Pay attention to the endpoint schemas when shaping requests: payloads for HTTP
- * methods without request bodies are encoded into URL parameters, multipart
- * payloads must be supplied as `FormData`, and response decoding can fail with
- * `SchemaError`. Declared error responses are decoded into the endpoint error
- * type, unknown statuses fail as `HttpClientError.DecodeError`, and failures while
- * decoding a declared error response include the original status-code failure.
- *
  * @since 4.0.0
  */
 export * as HttpApiClient from "./HttpApiClient.ts"
 
 /**
- * The `HttpApiEndpoint` module defines the per-route contracts used inside an
- * `HttpApiGroup`.
- *
- * An endpoint couples a stable name with an HTTP method and `HttpRouter` path,
- * plus schemas for path parameters, query parameters, headers, request payloads,
- * success responses, and declared errors. Server builders, generated clients,
- * and OpenAPI generation all read this metadata to decode requests, encode
- * responses, type handler inputs, and derive client call signatures.
- *
- * Use this module to declare individual operations such as `get`, `post`, `put`,
- * `patch`, `delete`, `head`, and `options`; attach endpoint-specific middleware
- * or annotations; and model alternatives for payloads, successes, and errors
- * with arrays of schemas.
- *
- * A few declaration details are worth keeping in mind. Paths use
- * `HttpRouter.PathInput`, so route parameters come from the router and are
- * decoded with the optional `params` schema. When codecs are enabled, params,
- * query, and headers are transformed through string-tree codecs; body methods
- * use JSON payload codecs by default, while no-body methods encode payloads as
- * query-style values. `HttpApiSchema` annotations can change payload or response
- * encodings and status codes, multipart payloads cannot be combined under the
- * same content type, and endpoint errors are merged with middleware errors for
- * server encoding and client decoding.
- *
  * @since 4.0.0
  */
 export * as HttpApiEndpoint from "./HttpApiEndpoint.ts"
 
 /**
- * The `HttpApiError` module defines the built-in error types used by Effect's
- * unstable HTTP API layer for common failure responses.
- *
- * Each exported status error is a `Schema.ErrorClass` with an `httpApiStatus`
- * annotation, so it can be declared as an endpoint or middleware error schema
- * and then used by reflection, OpenAPI generation, clients, and server response
- * encoding. The classes also implement `HttpServerRespondable`, which means
- * using one directly as a server response produces an empty response with the
- * matching HTTP status.
- *
- * Use the `*NoContent` variants when the wire response intentionally has no
- * body but clients should still decode that status into a typed error value.
- * For custom error schemas, make sure to add the intended
- * `HttpApiSchema.status` annotation; error schemas without one are treated as
- * `500 Internal Server Error` by the HTTP API machinery. Schema failures raised
- * while decoding params, headers, query, body, or payload values are represented
- * separately by `HttpApiSchemaError`, which responds as `400 Bad Request` unless
- * transformed by middleware.
- *
  * @since 4.0.0
  */
 export * as HttpApiError from "./HttpApiError.ts"
 
 /**
- * The `HttpApiGroup` module defines named collections of `HttpApiEndpoint`s
- * within an `HttpApi`.
- *
- * Groups are the main way to organize endpoints by a domain boundary, resource,
- * or feature area before those endpoints are added to an API and implemented
- * with `HttpApiBuilder.group`. A group carries its identifier, endpoint set,
- * annotations, and `topLevel` flag, which are later used by builders, clients,
- * URL builders, and OpenAPI generation. Non-top-level groups expose nested
- * client methods under the group name, while top-level groups expose their
- * endpoint methods directly.
- *
- * Composition is order-sensitive. Adding an endpoint with the same name as an
- * existing endpoint replaces it, and `prefix`, `middleware`,
- * `annotateEndpoints`, and `annotateEndpointsMerge` only affect endpoints that
- * are already present when those APIs are called. Group annotations apply to the
- * group itself; use the endpoint annotation helpers when metadata should be
- * attached to each endpoint.
- *
- * The type helpers in this module reflect the endpoint union for a group and
- * aggregate the services required by endpoint schemas, middleware, and declared
- * errors. Error schemas are still declared on endpoints, while middleware can
- * contribute additional error schemas and client/server service requirements
- * through the endpoint middleware set.
- *
  * @since 4.0.0
  */
 export * as HttpApiGroup from "./HttpApiGroup.ts"
 
 /**
- * The `HttpApiMiddleware` module defines middleware services that can wrap
- * `HttpApi` endpoint execution on the server and request execution in generated
- * clients.
- *
- * Use this module for cross-cutting HTTP API behavior such as authentication and
- * authorization, request logging or tracing, rate limiting, adding request-scoped
- * services to the endpoint context, normalizing schema errors, or installing
- * client-side request middleware for APIs that require the same concern on both
- * sides. Middleware services carry type-level metadata describing the services
- * they require and provide, the error schemas they may fail with, whether they
- * implement security schemes, and whether generated clients must provide a
- * matching client middleware.
- *
- * Security middleware is declared with non-empty `security` schemes and receives
- * decoded credentials from `HttpApiSecurity`; ordinary middleware receives only
- * endpoint and group metadata. Error declarations must be `Schema` values (or an
- * array of them) because middleware failures are added to the endpoint error
- * surface and must be encodable by the HTTP API builder. If a middleware turns
- * `HttpApiSchemaError` failures into API errors, use
- * `layerSchemaErrorTransform` and make sure the transformed error is covered by
- * the middleware's declared schema. Client middleware installed with
- * `layerClient` is made available through the `ForClient` marker and captures
- * its surrounding context, so client requirements should be declared explicitly
- * when `requiredForClient` is enabled.
- *
  * @since 4.0.0
  */
 export * as HttpApiMiddleware from "./HttpApiMiddleware.ts"
 
 /**
- * The `HttpApiScalar` module mounts an interactive Scalar API reference for a
- * declarative `HttpApi`.
- *
- * Use this module when you want a browser-friendly documentation page for an
- * `HttpApi` without maintaining a separate OpenAPI document. The `layer`
- * helper registers a `GET` route on an `HttpRouter`, generates the OpenAPI
- * specification with `OpenApi.fromApi`, embeds it into the HTML page, and loads
- * the bundled Scalar browser script. `layerCdn` provides the same UI while
- * loading Scalar from jsDelivr, optionally pinned with `version`.
- *
- * The mounted path is a documentation UI route, defaulting to `/docs`, rather
- * than a raw JSON specification endpoint. If clients, gateways, or external
- * documentation pipelines need the OpenAPI document directly, expose it
- * separately with `HttpApiBuilder.layer`'s `openapiPath` option. Scalar
- * configuration is forwarded to the page through `ScalarConfig`; values such as
- * `proxyUrl`, theme and layout settings, and `baseServerURL` matter when
- * enabling "Test Request", styling the docs, or rendering relative server URLs
- * outside the browser origin.
- *
  * @since 4.0.0
  */
 export * as HttpApiScalar from "./HttpApiScalar.ts"
 
 /**
- * Helpers for attaching HTTP API metadata to Effect Schema values.
- *
- * This module is the schema-side bridge used by the unstable HttpApi endpoint
- * builder, generated clients, and OpenAPI support. It does not define routes or
- * perform IO. Instead, helpers such as {@link status}, {@link asJson},
- * {@link asMultipart}, and {@link asNoContent} annotate schemas so downstream
- * HTTP tooling can choose response status codes, content types, body codecs, and
- * no-body handling while the original schema remains usable for validation and
- * transformation.
- *
- * Common use cases:
- * - Mark success or error schemas with explicit HTTP statuses using
- *   {@link status}, {@link NoContent}, {@link Created}, {@link Accepted}, or
- *   {@link Empty}.
- * - Override the default JSON encoding for request payloads or responses with
- *   {@link asFormUrlEncoded}, {@link asText}, {@link asUint8Array}, or
- *   {@link asJson}.
- * - Describe buffered or streaming multipart request payloads with
- *   {@link asMultipart} and {@link asMultipartStream}.
- * - Represent an HTTP response with no body while still decoding a client-side
- *   value through {@link asNoContent}.
- *
- * Status and encoding details:
- * - {@link status} only stores an annotation. The same annotation is interpreted
- *   by the surrounding HttpApi context; unannotated success responses default to
- *   `200`, and unannotated error responses default to `500`.
- * - Missing encodings default to JSON for bodies and responses. Payload schemas
- *   used with methods that have no request body fall back to form-url-encoded
- *   metadata for parameter encoding.
- * - {@link asFormUrlEncoded} expects the schema's encoded side to be a record
- *   of strings. {@link asText} expects `string`, and {@link asUint8Array}
- *   expects `Uint8Array`.
- * - Multipart encodings are payload-only; response multipart is rejected when
- *   response encoding is resolved.
- * - These helpers attach annotations consumed by HttpApi internals. They do not
- *   validate, encode, decode, or send data by themselves.
- *
  * @since 4.0.0
  */
 export * as HttpApiSchema from "./HttpApiSchema.ts"
 
 /**
- * The `HttpApiSecurity` module defines the security scheme values used by
- * declarative HTTP APIs.
- *
- * Use these constructors when an API group or endpoint needs authentication
- * middleware for bearer tokens, API keys, or HTTP Basic credentials. The values
- * are intentionally small declarations: `HttpApiMiddleware.Service` attaches
- * them to middleware, `HttpApiBuilder` decodes the matching credential shape from
- * each request, and OpenAPI generation emits the corresponding
- * `components.securitySchemes` and operation security requirements.
- *
- * Common uses include modeling `Authorization: Bearer ...` tokens, Basic
- * username/password credentials, and API keys passed through headers, query
- * parameters, or cookies. Bearer tokens and API-key values are exposed to
- * middleware as `Redacted` values; Basic credentials expose the username with a
- * redacted password. Cookie API keys can also be written to responses with
- * `HttpApiBuilder.securitySetCookie`.
- *
- * A security scheme does not authenticate by itself: middleware must reject empty
- * or invalid credentials. Bearer and Basic schemes read the `Authorization`
- * header, while API-key headers use HTTP header name normalization and API-key
- * query or cookie names are matched exactly. OpenAPI annotations such as
- * descriptions and bearer formats affect generated documentation only; they do
- * not change runtime decoding.
- *
  * @since 4.0.0
  */
 export * as HttpApiSecurity from "./HttpApiSecurity.ts"
 
 /**
- * Serves Swagger UI for an `HttpApi` by rendering the OpenAPI document generated
- * from the API directly into an HTML page.
- *
- * Use this module when you want a lightweight documentation route for a running
- * `HttpApi`, typically in development, staging, internal consoles, or public API
- * reference pages where Swagger UI's exploration and request-building tools are
- * preferred. The exported `layer` adds a `GET` route to an `HttpRouter`,
- * defaults the mount path to `/docs`, and leaves API implementation and server
- * wiring to `HttpApiBuilder` and the surrounding router layers.
- *
- * The page is self-contained: `OpenApi.fromApi` derives the specification from
- * the API's groups, endpoints, schemas, and OpenAPI annotations, then the JSON
- * is embedded into the HTML served to the browser. No separate `/openapi.json`
- * endpoint is installed by this module, so clients or documentation pipelines
- * that need the raw spec should use `OpenApi.fromApi` directly or expose a JSON
- * route elsewhere. If the docs are public, mount the layer behind the same
- * routing, security, or environment controls you want for the UI; generated
- * server URLs and operation metadata come from the API's OpenAPI annotations.
- *
  * @since 4.0.0
  */
 export * as HttpApiSwagger from "./HttpApiSwagger.ts"
 
 /**
- * The `HttpApiTest` module provides helpers for testing `HttpApi`
- * implementations through the generated client interface without starting an
- * HTTP server.
- *
- * Use this module when a test should exercise one or more implemented API
- * groups with the same request encoding, routing, response encoding, and client
- * decoding used by the production `HttpApiBuilder` and `HttpApiClient`
- * pipeline. This is useful for focused handler tests, schema round-trip checks,
- * middleware behavior, and tests that want to call an API through its typed
- * client while keeping all traffic in memory.
- *
- * The selected groups must be provided in the test environment, usually by
- * supplying the corresponding `HttpApiBuilder.group` layers. Groups that are not
- * selected are still present on the returned client shape, but their handlers
- * are placeholders that die if called, which helps catch accidental calls outside
- * the test scope. The generated client is still a real `HttpApiClient`, so
- * endpoint middleware, client middleware, platform services, and the optional
- * `baseUrl` used for URL construction follow the same rules as normal clients;
- * only the HTTP transport is replaced with an in-memory router dispatch.
- *
  * @since 4.0.0
  */
 export * as HttpApiTest from "./HttpApiTest.ts"
 
 /**
- * The `OpenApi` module converts declarative `HttpApi` definitions into
- * OpenAPI 3.1 specifications and provides annotations for shaping the
- * generated document.
- *
- * Use this module when you need to publish an `HttpApi` contract to tooling
- * such as Swagger UI, Scalar, client generators, API gateways, or documentation
- * pipelines. `fromApi` reflects the API's groups and endpoints into tags,
- * paths, operations, parameters, request bodies, responses, security schemes,
- * and component schemas while preserving Effect Schema metadata where OpenAPI
- * can represent it.
- *
- * The generated specification is driven by annotations on APIs, groups,
- * endpoints, security definitions, and schemas. `Title`, `Description`,
- * `Summary`, `Version`, `Servers`, `License`, `ExternalDocs`, `Identifier`,
- * `Deprecated`, and `Format` feed the corresponding OpenAPI fields; `Exclude`
- * omits a group or endpoint; `Override` shallowly merges custom fields; and
- * `Transform` can rewrite the generated API, tag, or operation object. Schema
- * identifiers are important for stable component names, additional schemas must
- * have identifiers, and invalid OpenAPI component keys are rejected during
- * generation.
- *
- * A few generation details are worth keeping in mind: `HttpApiSchema`
- * encodings choose media types and special representations for JSON,
- * form-url-encoded, text, binary, and multipart payloads; no-content schemas
- * emit responses without bodies; request and response unions are grouped by
- * status code and content type; path parameters are rendered from `:id` route
- * segments as `{id}`; and schemas are converted through the OpenAPI 3.1 JSON
- * Schema representation before being patched into the final document.
- *
  * @since 4.0.0
  */
 export * as OpenApi from "./OpenApi.ts"

package/src/unstable/observability/Otlp.ts

@@ -1,22 +1,37 @@
 /**
- * Convenience layers for exporting Effect logs, metrics, and traces over
- * OTLP/HTTP.
+ * Combined OTLP/HTTP export for Effect logs, metrics, and traces.
  *
- * This module wires the signal-specific OTLP logger, metrics, and tracer
- * exporters together so an application can install full observability with a
- * single layer. It is useful for services that report to an OpenTelemetry
- * Collector, vendor OTLP endpoint, or local collector during development
- * without configuring each signal independently.
+ * This module installs the signal-specific OTLP logger, metrics exporter, and
+ * tracer exporter from one shared configuration. Use it when an application
+ * sends all three observability signals to the same OpenTelemetry Collector,
+ * vendor OTLP intake, or local development collector and should not configure
+ * each exporter separately.
  *
- * Pass `baseUrl` as the OTLP/HTTP root URL, such as `http://localhost:4318`;
- * this module appends `/v1/logs`, `/v1/metrics`, and `/v1/traces` itself.
- * Use `layerJson` or `layerProtobuf` when you want the serialization layer
- * provided for you, or use `layer` with a custom `OtlpSerialization`
- * implementation. Configure authentication with `headers`, provide resource
- * metadata explicitly or through the standard OTEL resource environment
- * variables, and tune batch size, export intervals, metric temporality, and
- * shutdown timeout for the target backend so buffered telemetry is accepted
- * and flushed before shutdown.
+ * **Mental model**
+ *
+ * `baseUrl` is the OTLP/HTTP root, such as `http://localhost:4318`. The
+ * combined layer appends `/v1/logs`, `/v1/metrics`, and `/v1/traces`, then
+ * delegates batching, resource handling, and payload construction to the
+ * signal-specific modules. `layerJson` and `layerProtobuf` provide the
+ * serialization layer; `layer` leaves `OtlpSerialization` in the requirements
+ * so callers can provide a custom encoder.
+ *
+ * **Common tasks**
+ *
+ * - Use `layerJson` for JSON OTLP/HTTP endpoints and `layerProtobuf` for
+ *   protobuf endpoints.
+ * - Pass `headers` for collector authentication or routing.
+ * - Set `resource` to define service name, service version, and additional
+ *   resource attributes.
+ * - Tune export intervals, `maxBatchSize`, `metricsTemporality`, and
+ *   `shutdownTimeout` for the target backend.
+ *
+ * **Gotchas**
+ *
+ * Do not include a signal path in `baseUrl`; this module adds the paths itself.
+ * Buffered telemetry flushes when the scoped exporters finalize, subject to
+ * `shutdownTimeout`, so long-running services should keep the layer installed
+ * for the lifetime of the runtime.
  *
  * @since 4.0.0
  */

package/src/unstable/observability/OtlpLogger.ts

@@ -1,20 +1,36 @@
 /**
- * Exports Effect log records to an OpenTelemetry Protocol (OTLP) logs endpoint.
+ * OTLP/HTTP log exporter for Effect's logging system.
  *
- * Use this module to send Effect log messages, annotations, fiber identifiers,
- * causes, and active span identifiers to an OpenTelemetry Collector or OTLP
- * compatible observability backend. `make` is useful for custom logger wiring,
- * while `layer` installs the logger for an application and can merge it with
- * any existing loggers.
+ * This module turns Effect log entries into OTLP log records and sends them to
+ * a logs endpoint such as an OpenTelemetry Collector or vendor OTLP intake. It
+ * is the signal-specific logger used by the higher-level `Otlp` module when an
+ * application wants logs, metrics, and traces configured together.
  *
- * Records are buffered by the shared OTLP exporter. `exportInterval`,
- * `maxBatchSize`, and `shutdownTimeout` control periodic exports, early batch
- * flushes, and how long scope finalization waits for the final flush. Resource
- * options are attached to every export and override OpenTelemetry resource
- * environment variables, so ensure a `service.name` is available through the
- * options, `OTEL_RESOURCE_ATTRIBUTES`, or `OTEL_SERVICE_NAME`; use `headers`
- * for collector authentication and `excludeLogSpans` when log span duration
- * attributes would be too noisy.
+ * **Mental model**
+ *
+ * Each call to Effect logging APIs becomes one OTLP log record. The logger
+ * serializes the message body, severity, timestamp, fiber id, log annotations,
+ * failure cause, and current trace/span identifiers. Active log spans are
+ * exported as duration attributes named `logSpan.<label>` unless
+ * `excludeLogSpans` is enabled.
+ *
+ * **Common tasks**
+ *
+ * - Use `layer` to install the logger in an application; it merges with
+ *   existing loggers by default.
+ * - Use `make` when composing a custom `Logger` or logger layer manually.
+ * - Pass the concrete `/v1/logs` endpoint, or use `Otlp` when a shared
+ *   `baseUrl` should construct all signal paths.
+ * - Provide `headers` for collector authentication or routing, and choose an
+ *   `OtlpSerialization` layer accepted by the endpoint.
+ *
+ * **Gotchas**
+ *
+ * Batches are flushed on `exportInterval`, when `maxBatchSize` is reached, and
+ * during scope finalization up to `shutdownTimeout`. Resource options are
+ * attached to every export and override OpenTelemetry resource environment
+ * variables, so ensure a stable `service.name` is available through options,
+ * `OTEL_RESOURCE_ATTRIBUTES`, or `OTEL_SERVICE_NAME`.
  *
  * @since 4.0.0
  */
@@ -101,7 +117,7 @@ export const make: (
 })
 
 /**
- * Installs the OTLP logger created by `make` as an Effect logging layer.
+ * Layer that installs the OTLP logger created by `make`.
  *
  * **Details**
  *

package/src/unstable/observability/OtlpResource.ts

@@ -1,22 +1,40 @@
 /**
- * Helpers and data types for describing the OTLP resource attached to exported
- * logs, metrics, and traces.
+ * OTLP resource metadata for logs, metrics, and traces exported by Effect.
  *
- * A resource identifies the service that produced telemetry and carries
- * process- or deployment-level attributes that should be shared across every
- * signal sent by the Effect OTLP logger, metrics exporter, and tracer. Use this
- * module when building explicit resource metadata, reading the standard OTEL
- * resource environment variables, or converting application metadata into OTLP
- * `KeyValue` / `AnyValue` shapes before serialization.
+ * This module builds the resource object attached to every OTLP signal sent by
+ * the Effect observability exporters. A resource carries service identity such
+ * as `service.name` and `service.version`, plus process, host, deployment, or
+ * application attributes that should be shared by all exported telemetry.
+ *
+ * **Mental model**
+ *
+ * A {@link Resource} is the OTLP envelope for service-level metadata. Use
+ * {@link make} when the service metadata is already known, or use
+ * {@link fromConfig} when explicit options should be merged with standard
+ * OpenTelemetry environment variables before export. Attribute helpers convert
+ * JavaScript values into OTLP {@link KeyValue} and {@link AnyValue} structures
+ * used by JSON and protobuf serialization.
+ *
+ * **Common tasks**
+ *
+ * - Create explicit resource metadata with {@link make}.
+ * - Read `OTEL_RESOURCE_ATTRIBUTES`, `OTEL_SERVICE_NAME`, and
+ *   `OTEL_SERVICE_VERSION` with {@link fromConfig}.
+ * - Convert custom attribute records with {@link entriesToAttributes}.
+ * - Convert individual runtime values with {@link unknownToAttributeValue}.
+ *
+ * **Gotchas**
  *
  * `service.name` is required because the signal exporters also use it as the
- * instrumentation scope name. Explicit resource options take precedence over
- * `OTEL_RESOURCE_ATTRIBUTES`, `OTEL_SERVICE_NAME`, and
- * `OTEL_SERVICE_VERSION`; `service.name` and `service.version` are normalized
- * through the service metadata inputs and re-added as canonical OTLP
- * attributes rather than left in the custom attribute map. Attribute values are
- * converted to OTLP scalar or array values where possible, with unsupported
- * runtime values formatted as strings.
+ * instrumentation scope name. Explicit options take precedence over
+ * environment variables. `service.name` and `service.version` are normalized
+ * into canonical OTLP attributes instead of being left in the custom attribute
+ * map. Unsupported runtime values are formatted as strings.
+ *
+ * **See also**
+ *
+ * {@link Resource}, {@link make}, {@link fromConfig},
+ * {@link unknownToAttributeValue}.
  *
  * @since 4.0.0
  */

package/src/unstable/observability/OtlpSerialization.ts

@@ -1,20 +1,31 @@
 /**
- * Defines the serialization boundary used by the OTLP observability layers.
+ * OTLP/HTTP serialization service shared by logs, metrics, and traces.
  *
- * `OtlpSerialization` converts Effect's in-memory OTLP trace, metric, and log
- * data into `HttpBody` values so exporters can send them to collectors over
- * OTLP/HTTP. Use this module to choose between the JSON encoding that is useful
- * for debugging and collector endpoints that explicitly accept OTLP/HTTP JSON,
- * and the protobuf encoding commonly expected by production OpenTelemetry
- * collectors.
+ * This module decides how in-memory OTLP payloads become HTTP request bodies.
+ * The signal exporters build trace, metric, and log data structures, then call
+ * `OtlpSerialization` immediately before posting them to a collector.
  *
- * The JSON layer writes the telemetry structures directly with
- * `HttpBody.jsonUnsafe`; the protobuf layer encodes the same structures with
- * the internal OTLP protobuf encoder and sets the `application/x-protobuf`
- * content type. Endpoint paths, authentication headers, batching, retries, and
- * shutdown flushing are handled by the OTLP exporter layers that consume this
- * service, while this module focuses only on preserving the wire format chosen
- * for traces, metrics, and logs.
+ * **Mental model**
+ *
+ * `OtlpSerialization` has one encoder per OTLP signal. `layerJson` writes the
+ * structures directly with `HttpBody.jsonUnsafe`, which is useful for debugging
+ * or endpoints that explicitly accept OTLP/HTTP JSON. `layerProtobuf` encodes
+ * the same structures with the internal OTLP protobuf encoder and sets the
+ * `application/x-protobuf` content type expected by many production collectors.
+ *
+ * **Common tasks**
+ *
+ * - Provide `layerProtobuf` for collectors that expect binary OTLP payloads.
+ * - Provide `layerJson` when inspecting payloads or using an OTLP/HTTP JSON
+ *   endpoint.
+ * - Provide a custom `OtlpSerialization` service only when an exporter needs a
+ *   non-standard body format.
+ *
+ * **Gotchas**
+ *
+ * This module only controls the wire format for traces, metrics, and logs.
+ * Endpoint paths, authentication headers, batching, retries, and shutdown
+ * flushing are handled by the OTLP exporter layers that consume the service.
  *
  * @since 4.0.0
  */

package/src/unstable/observability/PrometheusMetrics.ts

@@ -101,7 +101,7 @@ export interface HttpOptions extends FormatOptions {
 }
 
 /**
- * Format all metrics in the registry to Prometheus exposition format.
+ * Formats all metrics in the registry to Prometheus exposition format.
  *
  * **Example** (Formatting metrics)
  *
@@ -139,11 +139,11 @@ export const format: (options?: FormatOptions | undefined) => Effect.Effect<stri
 )
 
 /**
- * Synchronously format all metrics in the registry to Prometheus exposition format.
+ * Formats all metrics in the registry to Prometheus exposition format synchronously.
  *
  * **When to use**
  *
- * Use this low-level function when you already have access to the context. Most
+ * Use when you use this low-level function when you already have access to the context. Most
  * users should use `format` instead.
  *
  * @category Formatting