@equipe-tech/observability 0.2.1 → 0.3.5

package/README.md

@@ -1,6 +1,6 @@
 # @equipe-tech/observability
 
-Biblioteca OpenTelemetry da Equipe Tech para aplicações Effect, Node.js, NestJS e browser.
+Núcleo neutro de observabilidade da Equipe Tech para OpenTelemetry, contratos, políticas e ciclo de vida.
 
 ## Instalação
 
@@ -8,17 +8,19 @@ Biblioteca OpenTelemetry da Equipe Tech para aplicações Effect, Node.js, NestJ
 npm install @equipe-tech/observability effect
 ```
 
+`effect@4.0.0-rc.111` é um peer obrigatório. O consumidor e os adapters compartilham a mesma cópia do runtime.
+
 ## Entrypoints
 
-- `@equipe-tech/observability`: configuração, eventos de browser e wide events.
-- `@equipe-tech/observability/metrics`: métricas imperativas sem tipos Effect na API pública.
-- `@equipe-tech/observability/node`: runtime OTLP para Node.js e ingestão de eventos do browser.
-- `@equipe-tech/observability/nestjs`: interceptor HTTP, módulo de ciclo de vida e correlação de eventos por requisição.
-- `@equipe-tech/observability/browser`: serviço Effect de telemetria do browser.
-- `@equipe-tech/observability/browser/client`: cliente imperativo de browser sem tipos Effect na API pública.
-- `@equipe-tech/observability/testing`: captura OTLP em memória para testes.
+- `@equipe-tech/observability` contém configuração, contratos, identidade, política e composição neutra.
+- `@equipe-tech/observability/effect` contém `WideEvent` e `layerWideEvent`.
+- `@equipe-tech/observability/metrics` contém métricas imperativas sem tipos Effect na API pública.
+- `@equipe-tech/observability/node` contém o runtime OTLP para Node.js e a ingestão de eventos do browser.
+- `@equipe-tech/observability/browser` contém o serviço Effect de telemetria do browser.
+- `@equipe-tech/observability/browser/client` contém o cliente imperativo sem tipos Effect na API pública.
+- `@equipe-tech/observability/testing` contém captura OTLP em memória para testes.
 
-O adapter NestJS suporta NestJS 10 e 11 com Express. Os peers NestJS e RxJS são opcionais para consumidores que não usam esse entrypoint.
+A integração NestJS pertence a `@equipe-tech/observability-nestjs`. O núcleo não importa NestJS, RxJS, reflect-metadata, evlog, React ou Sentry.
 
 Consulte a [documentação completa](https://github.com/equipe-tech/observability#readme) para configuração, política de dados, semântica HTTP e exemplos.
 

package/dist/BrowserEvents.d.ts

@@ -1,28 +1,78 @@
 import { Schema } from "effect";
-export declare const maxEventsPerBatch = 64;
-export declare const maxFieldsPerEvent = 32;
-export declare const maxFieldKeyLength = 128;
-export declare const maxFieldValueLength = 1024;
-export declare const maxEventNameLength = 128;
-export declare const maxEventIdLength = 64;
+export { browserEnvelopeVersion, browserRequestByteBudget, maxEventIdLength, maxEventNameLength, maxEventsPerBatch, maxFieldKeyLength, maxFieldsPerEvent, maxFieldValueLength, } from "./browser/BrowserEventLimits.js";
+export declare const maxBrowserEventOccurredAt = 18446744073709;
 declare const BrowserEventFields: Schema.$Record<Schema.NonEmptyString, Schema.Union<readonly [Schema.String, Schema.Number, Schema.Boolean]>>;
 export type BrowserEventFields = typeof BrowserEventFields.Type;
-declare const BrowserEvent_base: Schema.Class<BrowserEvent, Schema.Struct<{
-    readonly id: Schema.NonEmptyString;
+declare const BrowserResourceIdentity_base: Schema.Class<BrowserResourceIdentity, Schema.Struct<{
+    readonly serviceName: Schema.NonEmptyString;
+    readonly serviceVersion: Schema.NonEmptyString;
+    readonly environment: Schema.NonEmptyString;
+}>, {}>;
+export declare class BrowserResourceIdentity extends BrowserResourceIdentity_base {
+}
+declare const BrowserTraceContext_base: Schema.Class<BrowserTraceContext, Schema.Struct<{
+    readonly traceId: Schema.String;
+    readonly spanId: Schema.String;
+}>, {}>;
+export declare class BrowserTraceContext extends BrowserTraceContext_base {
+}
+declare const BrowserTraceSpan_base: Schema.Class<BrowserTraceSpan, Schema.Struct<{
+    readonly traceId: Schema.String;
+    readonly spanId: Schema.String;
+    readonly parentSpanId: Schema.optional<Schema.String>;
+    readonly name: Schema.NonEmptyString;
+    readonly startedAt: Schema.Number;
+    readonly endedAt: Schema.Number;
+    readonly fields: Schema.$Record<Schema.NonEmptyString, Schema.Union<readonly [Schema.String, Schema.Number, Schema.Boolean]>>;
+}>, {}>;
+export declare class BrowserTraceSpan extends BrowserTraceSpan_base {
+}
+declare const BrowserMetricPoint_base: Schema.Class<BrowserMetricPoint, Schema.Struct<{
     readonly name: Schema.NonEmptyString;
+    readonly value: Schema.Number;
     readonly occurredAt: Schema.Number;
     readonly fields: Schema.$Record<Schema.NonEmptyString, Schema.Union<readonly [Schema.String, Schema.Number, Schema.Boolean]>>;
 }>, {}>;
+export declare class BrowserMetricPoint extends BrowserMetricPoint_base {
+}
+declare const BrowserEventError_base: Schema.Class<BrowserEventError, Schema.Struct<{
+    readonly type: Schema.NonEmptyString;
+    readonly message: Schema.String;
+    readonly retryable: Schema.Boolean;
+}>, {}>;
+export declare class BrowserEventError extends BrowserEventError_base {
+}
+declare const BrowserEvent_base: Schema.Class<BrowserEvent, Schema.Struct<{
+    id: Schema.NonEmptyString;
+    name: Schema.NonEmptyString;
+    occurredAt: Schema.Number;
+    fields: Schema.$Record<Schema.NonEmptyString, Schema.Union<readonly [Schema.String, Schema.Number, Schema.Boolean]>>;
+    error: Schema.optional<typeof BrowserEventError>;
+    trace: Schema.optional<typeof BrowserTraceContext>;
+}>, {}>;
 export declare class BrowserEvent extends BrowserEvent_base {
 }
 declare const BrowserEventBatch_base: Schema.Class<BrowserEventBatch, Schema.Struct<{
-    readonly version: Schema.Literal<1>;
-    readonly events: Schema.$Array<typeof BrowserEvent>;
+    version: Schema.Int;
+    resource: Schema.optional<typeof BrowserResourceIdentity>;
+    events: Schema.$Array<typeof BrowserEvent>;
+    spans: Schema.optional<Schema.$Array<typeof BrowserTraceSpan>>;
+    metrics: Schema.optional<Schema.$Array<typeof BrowserMetricPoint>>;
 }>, {}>;
 export declare class BrowserEventBatch extends BrowserEventBatch_base {
 }
+export declare const browserEnvelopeMetadata: {
+    version: number;
+    batchFields: string[];
+    eventFields: string[];
+};
 export declare const encodeBrowserEventBatch: (input: BrowserEventBatch, options?: import("effect/SchemaAST").ParseOptions) => import("effect/Effect").Effect<{
-    readonly version: 1;
+    readonly version: number;
+    readonly resource?: {
+        readonly serviceName: string;
+        readonly serviceVersion: string;
+        readonly environment: string;
+    } | undefined;
     readonly events: readonly {
         readonly id: string;
         readonly name: string;
@@ -30,6 +80,33 @@ export declare const encodeBrowserEventBatch: (input: BrowserEventBatch, options
         readonly fields: {
             readonly [x: string]: string | number | boolean;
         };
+        readonly error?: {
+            readonly type: string;
+            readonly message: string;
+            readonly retryable: boolean;
+        } | undefined;
+        readonly trace?: {
+            readonly traceId: string;
+            readonly spanId: string;
+        } | undefined;
     }[];
+    readonly spans?: readonly {
+        readonly traceId: string;
+        readonly spanId: string;
+        readonly parentSpanId?: string | undefined;
+        readonly name: string;
+        readonly startedAt: number;
+        readonly endedAt: number;
+        readonly fields: {
+            readonly [x: string]: string | number | boolean;
+        };
+    }[] | undefined;
+    readonly metrics?: readonly {
+        readonly name: string;
+        readonly value: number;
+        readonly occurredAt: number;
+        readonly fields: {
+            readonly [x: string]: string | number | boolean;
+        };
+    }[] | undefined;
 }, Schema.SchemaError, never>;
-export {};

package/dist/BrowserEvents.js

@@ -1,10 +1,8 @@
 import { Schema } from "effect";
-export const maxEventsPerBatch = 64;
-export const maxFieldsPerEvent = 32;
-export const maxFieldKeyLength = 128;
-export const maxFieldValueLength = 1024;
-export const maxEventNameLength = 128;
-export const maxEventIdLength = 64;
+import { maxOtlpUnixTimestampMillis } from "./contract/TelemetryEvent.js";
+import { browserEnvelopeVersion, maxEventIdLength, maxEventNameLength, maxEventsPerBatch, maxFieldKeyLength, maxFieldsPerEvent, maxFieldValueLength, } from "./browser/BrowserEventLimits.js";
+export { browserEnvelopeVersion, browserRequestByteBudget, maxEventIdLength, maxEventNameLength, maxEventsPerBatch, maxFieldKeyLength, maxFieldsPerEvent, maxFieldValueLength, } from "./browser/BrowserEventLimits.js";
+export const maxBrowserEventOccurredAt = maxOtlpUnixTimestampMillis;
 const BoundedFieldValue = Schema.Union([
     Schema.String.check(Schema.isMaxLength(maxFieldValueLength)),
     Schema.Number.check(Schema.isFinite()),
@@ -14,20 +12,76 @@ const BoundedFieldKey = Schema.NonEmptyString.check(Schema.isMaxLength(maxFieldK
 const BrowserEventFields = Schema.Record(BoundedFieldKey, BoundedFieldValue).check(Schema.makeFilter((fields) => Object.keys(fields).length <= maxFieldsPerEvent, {
     expected: `at most ${maxFieldsPerEvent} fields per event`,
 }));
-export class BrowserEvent extends Schema.Class("@equipe-tech/observability/BrowserEvent")({
+const BrowserTraceId = Schema.String.check(Schema.isPattern(/^[0-9a-f]{32}$/), Schema.makeFilter((value) => value !== "00000000000000000000000000000000", {
+    expected: "a non-zero W3C trace identifier",
+}));
+const BrowserSpanId = Schema.String.check(Schema.isPattern(/^[0-9a-f]{16}$/), Schema.makeFilter((value) => value !== "0000000000000000", {
+    expected: "a non-zero W3C span identifier",
+}));
+export class BrowserResourceIdentity extends Schema.Class("@equipe-tech/observability/BrowserResourceIdentity")({
+    serviceName: Schema.NonEmptyString,
+    serviceVersion: Schema.NonEmptyString,
+    environment: Schema.NonEmptyString,
+}) {
+}
+export class BrowserTraceContext extends Schema.Class("@equipe-tech/observability/BrowserTraceContext")({
+    traceId: BrowserTraceId,
+    spanId: BrowserSpanId,
+}) {
+}
+export class BrowserTraceSpan extends Schema.Class("@equipe-tech/observability/BrowserTraceSpan")({
+    traceId: BrowserTraceId,
+    spanId: BrowserSpanId,
+    parentSpanId: Schema.optional(BrowserSpanId),
+    name: Schema.NonEmptyString.check(Schema.isMaxLength(maxEventNameLength)),
+    startedAt: Schema.Number.check(Schema.isFinite(), Schema.isBetween({ minimum: 0, maximum: maxBrowserEventOccurredAt })),
+    endedAt: Schema.Number.check(Schema.isFinite(), Schema.isBetween({ minimum: 0, maximum: maxBrowserEventOccurredAt })),
+    fields: BrowserEventFields,
+}) {
+}
+export class BrowserMetricPoint extends Schema.Class("@equipe-tech/observability/BrowserMetricPoint")({
+    name: Schema.NonEmptyString.check(Schema.isMaxLength(maxEventNameLength)),
+    value: Schema.Number.check(Schema.isFinite(), Schema.isGreaterThanOrEqualTo(0)),
+    occurredAt: Schema.Number.check(Schema.isFinite(), Schema.isBetween({ minimum: 0, maximum: maxBrowserEventOccurredAt })),
+    fields: BrowserEventFields,
+}) {
+}
+export class BrowserEventError extends Schema.Class("@equipe-tech/observability/BrowserEventError")({
+    type: Schema.NonEmptyString.check(Schema.isMaxLength(maxFieldValueLength)),
+    message: Schema.String.check(Schema.isMaxLength(maxFieldValueLength)),
+    retryable: Schema.Boolean,
+}) {
+}
+const BrowserEventDocument = {
     id: Schema.NonEmptyString.check(Schema.isMaxLength(maxEventIdLength)),
     name: Schema.NonEmptyString.check(Schema.isMaxLength(maxEventNameLength)),
-    occurredAt: Schema.Number.check(Schema.isFinite(), Schema.makeFilter((millis) => millis >= 0, {
-        expected: "a non-negative epoch timestamp in milliseconds",
+    occurredAt: Schema.Number.check(Schema.isFinite(), Schema.makeFilter((millis) => millis >= 0 && millis <= maxBrowserEventOccurredAt, {
+        expected: `an epoch timestamp in milliseconds from 0 through ${maxBrowserEventOccurredAt}`,
     })),
     fields: BrowserEventFields,
-}) {
+    error: Schema.optional(BrowserEventError),
+    trace: Schema.optional(BrowserTraceContext),
+};
+export class BrowserEvent extends Schema.Class("@equipe-tech/observability/BrowserEvent")(BrowserEventDocument) {
 }
-export class BrowserEventBatch extends Schema.Class("@equipe-tech/observability/BrowserEventBatch")({
-    version: Schema.Literal(1),
+const BrowserEventBatchDocument = {
+    version: Schema.Int.check(Schema.isGreaterThan(0), Schema.makeFilter(Number.isSafeInteger, { expected: "a positive safe integer" })),
+    resource: Schema.optional(BrowserResourceIdentity),
     events: Schema.Array(BrowserEvent).check(Schema.makeFilter((events) => events.length <= maxEventsPerBatch, {
         expected: `at most ${maxEventsPerBatch} events per batch`,
     })),
-}) {
+    spans: Schema.optional(Schema.Array(BrowserTraceSpan).check(Schema.makeFilter((spans) => spans.length <= maxEventsPerBatch, {
+        expected: `at most ${maxEventsPerBatch} spans per batch`,
+    }))),
+    metrics: Schema.optional(Schema.Array(BrowserMetricPoint).check(Schema.makeFilter((metrics) => metrics.length <= maxEventsPerBatch, {
+        expected: `at most ${maxEventsPerBatch} metric points per batch`,
+    }))),
+};
+export class BrowserEventBatch extends Schema.Class("@equipe-tech/observability/BrowserEventBatch")(BrowserEventBatchDocument) {
 }
+export const browserEnvelopeMetadata = {
+    version: browserEnvelopeVersion,
+    batchFields: Object.keys(BrowserEventBatchDocument).sort(),
+    eventFields: Object.keys(BrowserEventDocument).sort(),
+};
 export const encodeBrowserEventBatch = Schema.encodeEffect(BrowserEventBatch);

package/dist/Correlation.d.ts

@@ -0,0 +1,51 @@
+import { Context, Effect, Option, Schema } from "effect";
+export declare const TraceId: Schema.brand<Schema.String, "TraceId">;
+export type TraceId = typeof TraceId.Type;
+export declare const SpanId: Schema.brand<Schema.String, "SpanId">;
+export type SpanId = typeof SpanId.Type;
+export declare const RequestId: Schema.brand<Schema.NonEmptyString, "RequestId">;
+export type RequestId = typeof RequestId.Type;
+export declare const RunId: Schema.brand<Schema.NonEmptyString, "RunId">;
+export type RunId = typeof RunId.Type;
+export declare const TraceLinkage: Schema.Union<readonly [Schema.Struct<{
+    readonly _tag: Schema.Literal<"Untraced">;
+}>, Schema.Struct<{
+    readonly _tag: Schema.Literal<"Traced">;
+    readonly traceId: Schema.brand<Schema.String, "TraceId">;
+    readonly spanId: Schema.brand<Schema.String, "SpanId">;
+}>]>;
+export type TraceLinkage = typeof TraceLinkage.Type;
+declare const CorrelationContext_base: Schema.Class<CorrelationContext, Schema.Struct<{
+    readonly trace: Schema.withConstructorDefault<Schema.Union<readonly [Schema.Struct<{
+        readonly _tag: Schema.Literal<"Untraced">;
+    }>, Schema.Struct<{
+        readonly _tag: Schema.Literal<"Traced">;
+        readonly traceId: Schema.brand<Schema.String, "TraceId">;
+        readonly spanId: Schema.brand<Schema.String, "SpanId">;
+    }>]>>;
+    readonly requestId: Schema.withConstructorDefault<Schema.Option<Schema.brand<Schema.NonEmptyString, "RequestId">>>;
+    readonly runId: Schema.withConstructorDefault<Schema.Option<Schema.brand<Schema.NonEmptyString, "RunId">>>;
+}>, {}>;
+export declare class CorrelationContext extends CorrelationContext_base {
+    get traceId(): Option.Option<TraceId>;
+    get spanId(): Option.Option<SpanId>;
+}
+export declare const CorrelationField: Schema.Literals<readonly ["traceId", "spanId", "requestId", "runId"]>;
+export type CorrelationField = typeof CorrelationField.Type;
+declare const InvalidCorrelationContext_base: Schema.Class<InvalidCorrelationContext, Schema.TaggedStruct<"InvalidCorrelationContext", {
+    readonly code: Schema.Literal<"OBS_CORRELATION_INVALID">;
+    readonly message: Schema.String;
+    readonly field: Schema.Literals<readonly ["traceId", "spanId", "requestId", "runId"]>;
+    readonly rule: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class InvalidCorrelationContext extends InvalidCorrelationContext_base {
+}
+export declare const parseTraceId: (value: string) => Effect.Effect<TraceId, InvalidCorrelationContext>;
+export declare const parseSpanId: (value: string) => Effect.Effect<SpanId, InvalidCorrelationContext>;
+export declare const parseRequestId: (value: string) => Effect.Effect<RequestId, InvalidCorrelationContext>;
+export declare const parseRunId: (value: string) => Effect.Effect<RunId, InvalidCorrelationContext>;
+export declare const generateRunId: (kind: "canary" | "job", label: string) => Effect.Effect<string & import("effect/Brand").Brand<"RunId">, never, never>;
+export declare const CurrentCorrelation: Context.Reference<CorrelationContext>;
+export declare const withCorrelation: (correlation: CorrelationContext) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+export declare const withBackgroundCorrelation: (correlation: CorrelationContext, spanName: string) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+export {};

package/dist/Correlation.js

@@ -0,0 +1,95 @@
+import { Clock, Context, Effect, Option, Random, Schema, Tracer } from "effect";
+const containsControlCharacter = (value) => {
+    for (const character of value) {
+        const codePoint = character.codePointAt(0);
+        if (codePoint !== undefined && (codePoint <= 31 || codePoint === 127)) {
+            return true;
+        }
+    }
+    return false;
+};
+export const TraceId = Schema.String.check(Schema.isPattern(/^[0-9a-f]{32}$/), Schema.makeFilter((value) => value !== "0".repeat(32), { expected: "a non-zero trace ID" })).pipe(Schema.brand("TraceId"));
+export const SpanId = Schema.String.check(Schema.isPattern(/^[0-9a-f]{16}$/), Schema.makeFilter((value) => value !== "0".repeat(16), { expected: "a non-zero span ID" })).pipe(Schema.brand("SpanId"));
+export const RequestId = Schema.NonEmptyString.check(Schema.makeFilter((value) => !containsControlCharacter(value), {
+    expected: "a value without control characters",
+}), Schema.isMaxLength(128)).pipe(Schema.brand("RequestId"));
+export const RunId = Schema.NonEmptyString.check(Schema.makeFilter((value) => !containsControlCharacter(value), {
+    expected: "a value without control characters",
+}), Schema.isMaxLength(128)).pipe(Schema.brand("RunId"));
+export const TraceLinkage = Schema.Union([
+    Schema.Struct({ _tag: Schema.Literal("Untraced") }),
+    Schema.Struct({ _tag: Schema.Literal("Traced"), traceId: TraceId, spanId: SpanId }),
+]);
+export class CorrelationContext extends Schema.Class("@equipe-tech/observability/CorrelationContext")({
+    trace: TraceLinkage.pipe(Schema.withConstructorDefault(Effect.succeed({ _tag: "Untraced" }))),
+    requestId: Schema.Option(RequestId).pipe(Schema.withConstructorDefault(Effect.succeed(Option.none()))),
+    runId: Schema.Option(RunId).pipe(Schema.withConstructorDefault(Effect.succeed(Option.none()))),
+}) {
+    get traceId() {
+        return this.trace._tag === "Traced" ? Option.some(this.trace.traceId) : Option.none();
+    }
+    get spanId() {
+        return this.trace._tag === "Traced" ? Option.some(this.trace.spanId) : Option.none();
+    }
+}
+export const CorrelationField = Schema.Literals(["traceId", "spanId", "requestId", "runId"]);
+export class InvalidCorrelationContext extends Schema.TaggedError()("InvalidCorrelationContext", {
+    code: Schema.Literal("OBS_CORRELATION_INVALID"),
+    message: Schema.String,
+    field: CorrelationField,
+    rule: Schema.String,
+}) {
+}
+const invalidCorrelation = (field, rule) => new InvalidCorrelationContext({
+    code: "OBS_CORRELATION_INVALID",
+    field,
+    rule,
+    message: `Correlation field ${field} is invalid. Use ${rule}.`,
+});
+const traceIdRule = "32 lowercase hexadecimal characters and a non-zero value";
+const spanIdRule = "16 lowercase hexadecimal characters and a non-zero value";
+const opaqueIdentifierRule = "1 to 128 characters without control characters";
+const decodeTraceId = Schema.decodeUnknownEffect(TraceId);
+const decodeSpanId = Schema.decodeUnknownEffect(SpanId);
+const decodeRequestId = Schema.decodeUnknownEffect(RequestId);
+const decodeRunId = Schema.decodeUnknownEffect(RunId);
+export const parseTraceId = (value) => decodeTraceId(value).pipe(Effect.mapError(() => invalidCorrelation("traceId", traceIdRule)));
+export const parseSpanId = (value) => decodeSpanId(value).pipe(Effect.mapError(() => invalidCorrelation("spanId", spanIdRule)));
+export const parseRequestId = (value) => decodeRequestId(value).pipe(Effect.mapError(() => invalidCorrelation("requestId", opaqueIdentifierRule)));
+export const parseRunId = (value) => decodeRunId(value).pipe(Effect.mapError(() => invalidCorrelation("runId", opaqueIdentifierRule)));
+const dnsSafeLabel = (label) => {
+    const normalized = label
+        .toLowerCase()
+        .replaceAll(/[^a-z0-9-]+/g, "-")
+        .replaceAll(/-+/g, "-")
+        .replaceAll(/^-+|-+$/g, "");
+    return normalized === "" ? "run" : normalized;
+};
+export const generateRunId = Effect.fn("generateRunId")(function* (kind, label) {
+    const prefix = kind === "canary" ? "test" : "job";
+    const timestamp = yield* Clock.currentTimeMillis;
+    const entropy = Math.floor((yield* Random.next) * 2_821_109_907_456)
+        .toString(36)
+        .padStart(8, "0");
+    const suffix = `-${timestamp}-${entropy}`;
+    const truncatedLabel = dnsSafeLabel(label)
+        .slice(0, 128 - prefix.length - suffix.length - 1)
+        .replaceAll(/-+$/g, "");
+    const boundedLabel = truncatedLabel === "" ? "run" : truncatedLabel;
+    return yield* decodeRunId(`${prefix}-${boundedLabel}${suffix}`).pipe(Effect.orDie);
+});
+const emptyCorrelation = new CorrelationContext({});
+export const CurrentCorrelation = Context.Reference("@equipe-tech/observability/CurrentCorrelation", { defaultValue: () => emptyCorrelation });
+export const withCorrelation = (correlation) => (effect) => Effect.provideService(effect, CurrentCorrelation, correlation);
+export const withBackgroundCorrelation = (correlation, spanName) => (effect) => {
+    const correlated = Effect.provideService(effect, CurrentCorrelation, correlation);
+    if (correlation.trace._tag === "Traced") {
+        return correlated.pipe(Effect.withSpan(spanName, {
+            parent: Tracer.externalSpan({
+                traceId: correlation.trace.traceId,
+                spanId: correlation.trace.spanId,
+            }),
+        }));
+    }
+    return correlated.pipe(Effect.withSpan(spanName, { root: true }));
+};

package/dist/Metrics.d.ts

@@ -1,3 +1,8 @@
+import type { MetricMeasurementErrorCode } from "./contract/MetricContractError.js";
+import type { EnvironmentAliasPolicy, ResourceIdentityField } from "./ResourceIdentity.js";
+import type { DataPolicy } from "./policy/DataPolicy.js";
+import type { MetricLabelRejection } from "./policy/MetricLabelPolicy.js";
+export type { MetricLabelRejection } from "./policy/MetricLabelPolicy.js";
 export type MetricAttributeValue = string | number | boolean;
 export interface MetricAttribute {
     readonly key: string;
@@ -28,11 +33,13 @@ export interface ObservableGaugeRegistration {
     unregister(): void;
     [Symbol.dispose](): void;
 }
-export type GaugeCollectionFailureCode = "CALLBACK_FAILED" | "INVALID_OBSERVATION" | "ATTRIBUTE_LIMIT_EXCEEDED" | "SERIES_LIMIT_EXCEEDED";
+export type GaugeCollectionFailureCode = "CALLBACK_FAILED" | "INVALID_OBSERVATION" | "ATTRIBUTE_LIMIT_EXCEEDED" | "SERIES_LIMIT_EXCEEDED" | "POLICY_BLOCKED" | "CONTRACT_REJECTED";
 export interface GaugeCollectionFailure {
     readonly instrumentName: string;
     readonly code: GaugeCollectionFailureCode;
     readonly message: string;
+    readonly policyReason?: MetricLabelRejection;
+    readonly contractReason?: MetricMeasurementErrorCode;
 }
 export interface FlushResult {
     readonly gaugeFailures: ReadonlyArray<GaugeCollectionFailure>;
@@ -49,16 +56,22 @@ export interface MetricsOptions {
     readonly serviceName: string;
     readonly serviceVersion: string;
     readonly environment: string;
+    readonly deploymentEnvironmentAlias?: EnvironmentAliasPolicy | undefined;
     readonly otlpEndpoint: string;
     readonly exportIntervalMilliseconds?: number;
     readonly flushTimeoutMilliseconds?: number;
+    readonly policy?: DataPolicy;
 }
-export type MetricsErrorCode = "INVALID_CONFIGURATION" | "INVALID_INSTRUMENT" | "INVALID_MEASUREMENT" | "INSTRUMENT_CONFLICT" | "LIMIT_EXCEEDED" | "EXPORT_FAILED" | "FLUSH_TIMED_OUT" | "CLOSED";
+export type MetricsErrorCode = "INVALID_CONFIGURATION" | "INVALID_INSTRUMENT" | "INVALID_MEASUREMENT" | "INSTRUMENT_CONFLICT" | "LIMIT_EXCEEDED" | "EXPORT_FAILED" | "FLUSH_TIMED_OUT" | "POLICY_BLOCKED" | "CLOSED";
 interface MetricsErrorOptions {
     readonly code: MetricsErrorCode;
     readonly operation: string;
     readonly message: string;
     readonly instrumentName?: string;
+    readonly attributeKey?: string;
+    readonly policyReason?: MetricLabelRejection;
+    readonly field?: ResourceIdentityField;
+    readonly rule?: string;
     readonly retryable: boolean;
     readonly cause?: unknown;
 }
@@ -66,9 +79,12 @@ export declare class MetricsError extends Error {
     readonly code: MetricsErrorCode;
     readonly operation: string;
     readonly instrumentName?: string;
+    readonly attributeKey?: string;
+    readonly policyReason?: MetricLabelRejection;
+    readonly field?: ResourceIdentityField;
+    readonly rule?: string;
     readonly retryable: boolean;
     readonly cause?: unknown;
     constructor(options: MetricsErrorOptions);
 }
 export declare const createMetrics: (options: MetricsOptions) => Promise<Metrics>;
-export {};

package/dist/Metrics.js

@@ -3,6 +3,10 @@ export class MetricsError extends Error {
     code;
     operation;
     instrumentName;
+    attributeKey;
+    policyReason;
+    field;
+    rule;
     retryable;
     cause;
     constructor(options) {
@@ -13,6 +17,18 @@ export class MetricsError extends Error {
         if (options.instrumentName !== undefined) {
             this.instrumentName = options.instrumentName;
         }
+        if (options.attributeKey !== undefined) {
+            this.attributeKey = options.attributeKey;
+        }
+        if (options.policyReason !== undefined) {
+            this.policyReason = options.policyReason;
+        }
+        if (options.field !== undefined) {
+            this.field = options.field;
+        }
+        if (options.rule !== undefined) {
+            this.rule = options.rule;
+        }
         this.retryable = options.retryable;
         this.cause = options.cause;
     }

package/dist/MetricsRuntime.d.ts

@@ -1,11 +1,53 @@
-import { Layer } from "effect";
+import { Context, Layer } from "effect";
 import { HttpClient } from "effect/unstable/http";
 import { OtlpExporter } from "effect/unstable/observability";
-import type { Metrics, MetricsOptions } from "./Metrics.js";
+import type { CounterDefinition, GaugeObservation, MetricAttribute, MetricAttributeValue, Metrics, MetricsOptions } from "./Metrics.js";
 import type { TelemetryConfig } from "./TelemetryConfig.js";
+import { type DataPolicy } from "./policy/DataPolicy.js";
+type ContractCardinalityLimit = {
+    readonly attributeName: string;
+    readonly maximumCardinality: number;
+};
+type ContractMetricDefinitionIdentity = {
+    readonly alias: string;
+    readonly name: string;
+    readonly kind: "counter" | "histogram" | "observable_gauge";
+};
+type ContractMetricAttribute = {
+    readonly key: string;
+    readonly value: MetricAttributeValue;
+};
+export type ContractMetricAdmission = {
+    readonly metrics: Metrics;
+    readonly metricAlias: string;
+    readonly metricName: string;
+    readonly definitionIdentity: ContractMetricDefinitionIdentity;
+    readonly attributes: ReadonlyArray<ContractMetricAttribute>;
+    readonly limits: ReadonlyArray<ContractCardinalityLimit>;
+};
+type ContractGaugeObservation = ContractMetricAdmission;
+export declare const registerContractGaugeObservation: (observation: GaugeObservation, contract: ContractGaugeObservation) => GaugeObservation;
+export type MetricCounterBatchMeasurement = {
+    readonly definition: CounterDefinition;
+    readonly value: number;
+    readonly attributes: ReadonlyArray<MetricAttribute>;
+    readonly admission: ContractMetricAdmission;
+};
+export declare const reserveMetricCounterBatch: (metrics: Metrics, measurements: ReadonlyArray<MetricCounterBatchMeasurement>) => (() => void);
+export declare const prepareContractMetricBatch: (admissions: ReadonlyArray<ContractMetricAdmission>) => (() => void);
+export declare const prepareContractMetricAttributes: (metrics: Metrics, metricAlias: string, metricName: string, definitionIdentity: ContractMetricDefinitionIdentity, attributes: ReadonlyArray<ContractMetricAttribute>, limits: ReadonlyArray<ContractCardinalityLimit>) => (() => void);
+export declare const releaseMetricsLease: (metrics: Metrics) => Promise<void>;
+export declare const createDisabledMetrics: (policy?: DataPolicy) => Metrics;
 export declare const createStandaloneMetrics: (optionsInput: MetricsOptions) => Promise<Metrics>;
 interface LayerMetricsOptions {
     readonly shutdownTimeoutMilliseconds: number;
+    readonly policy: DataPolicy;
+    readonly resourceAttributes: ReadonlyMap<string, string>;
 }
-export declare const layerMetricsRuntime: (config: TelemetryConfig, options: LayerMetricsOptions) => Layer.Layer<OtlpExporter.Flusher, never, HttpClient.HttpClient>;
+declare const LayerMetricsRuntime_base: Context.ServiceClass<LayerMetricsRuntime, "@equipe-tech/observability/internal/LayerMetricsRuntime", {
+    readonly acquireMetrics: () => Metrics;
+}>;
+export declare class LayerMetricsRuntime extends LayerMetricsRuntime_base {
+}
+export declare const layerMetricsRuntime: (config: TelemetryConfig, options: LayerMetricsOptions) => Layer.Layer<OtlpExporter.Flusher | LayerMetricsRuntime, never, HttpClient.HttpClient>;
 export {};