fix(observability): align OTLP exporter, resource and logger with the OpenTelemetry spec

.changeset/otlp-exporters-semconv.md

@@ -0,0 +1,6 @@
+---
+"effect": patch
+"@effect/opentelemetry": patch
+---
+
+Align OTLP and `@effect/opentelemetry` logs, traces, and resources with OpenTelemetry conventions.

package.json

@@ -30,7 +30,7 @@
     "ai-docgen:watch": "pnpm ai-docgen --watch",
     "api-diff": "pnpm --dir packages/tools/api-diff exec node src/bin.ts",
     "test-types": "tstyche --target '>=5.9'",
-    "changeset-version": "changeset version",
+    "changeset-version": "changeset version && node scripts/version.mjs",
     "changeset-publish": "node scripts/set-strip-internal.mjs && pnpm codemod && pnpm build && changeset publish"
   },
   "devDependencies": {

packages/effect/src/Version.ts

@@ -0,0 +1,35 @@
+/**
+ * The `effect` package version used in telemetry headers, resources, and scopes.
+ *
+ * @since 4.0.2
+ */
+import { version } from "./internal/version.ts"
+
+let currentVersion: string = version
+
+/**
+ * Returns the current version of the `effect` package.
+ *
+ * **Details**
+ *
+ * Defaults to the release version unless overridden by `setCurrentVersion`.
+ *
+ * @category getters
+ * @since 4.0.2
+ */
+export const getCurrentVersion = (): string => currentVersion
+
+/**
+ * Overrides the version returned by `getCurrentVersion`.
+ *
+ * **Gotchas**
+ *
+ * Applies to this copy of the module. Existing telemetry layers retain the
+ * version they read when built.
+ *
+ * @category setters
+ * @since 4.0.2
+ */
+export const setCurrentVersion = (version: string): void => {
+  currentVersion = version
+}

packages/effect/src/index.ts

@@ -721,3 +721,8 @@ export * as Unify from "./Unify.ts"
  * @since 2.0.0
  */
 export * as Utils from "./Utils.ts"
+
+/**
+ * @since 4.0.2
+ */
+export * as Version from "./Version.ts"

packages/effect/src/internal/version.ts

@@ -0,0 +1,2 @@
+/** @internal */
+export const version = "4.0.1"

packages/effect/src/observability/OtlpExporter.ts

@@ -26,6 +26,7 @@ import * as Num from "../Number.ts"
 import * as Option from "../Option.ts"
 import * as Schedule from "../Schedule.ts"
 import * as Scope from "../Scope.ts"
+import * as Version from "../Version.ts"
 
 const retryAfterDelay = (value: string | undefined): Effect.Effect<Duration.Duration> => {
   const seconds = Option.fromUndefinedOr(value).pipe(Option.flatMap(Num.parse))
@@ -194,12 +195,14 @@ export const make: (
     HttpClient.retryTransient({ schedule: policy, times: 3 })
   )
 
-  let headers = Headers.fromRecordUnsafe({
-    "user-agent": `effect-opentelemetry-${options.label}/0.0.0`
-  })
-  if (options.headers) {
-    headers = Headers.merge(Headers.fromInput(options.headers), headers)
-  }
+  const exporterUserAgent = `OTel-OTLP-Exporter-JavaScript-Effect-${options.label}/${Version.getCurrentVersion()}`
+  const userHeaders = Headers.fromInput(options.headers)
+  const userAgent = userHeaders["user-agent"]
+  const headers = Headers.set(
+    userHeaders,
+    "user-agent",
+    userAgent ? `${userAgent} ${exporterUserAgent}` : exporterUserAgent
+  )
 
   const request = HttpClientRequest.post(options.url, { headers })
   let buffer: Array<any> = []

packages/effect/src/observability/OtlpLogger.ts

@@ -23,6 +23,7 @@ import type * as LogLevel from "../LogLevel.ts"
 import * as Option from "../Option.ts"
 import { CurrentLogAnnotations, CurrentLogSpans } from "../References.ts"
 import type * as Scope from "../Scope.ts"
+import * as Version from "../Version.ts"
 import * as OtlpEnv from "./internal/otlpEnv.ts"
 import * as Exporter from "./OtlpExporter.ts"
 import type { AnyValue, Fixed64, KeyValue, Resource } from "./OtlpResource.ts"
@@ -64,7 +65,8 @@ export const make: (
   const serialization = yield* OtlpSerialization
   const otelResource = yield* OtlpResource.fromConfig(options.resource)
   const scope: IInstrumentationScope = {
-    name: OtlpResource.serviceNameUnsafe(otelResource)
+    name: "effect",
+    version: Version.getCurrentVersion()
   }
 
   const exporter = yield* Exporter.make({
@@ -192,42 +194,39 @@ export interface LogsData {
 
 // internal
 
+const nanosPerMilli = BigInt(1_000_000)
+
 const makeLogRecord = (options: Logger.Options<unknown>, opts: {
   readonly excludeLogSpans: boolean
   readonly clock: Clock
 }): ILogRecord => {
-  const now = opts.clock.currentTimeNanosUnsafe()
-  const nanosString = now.toString()
-  const nowMillis = options.date.getTime()
+  const observedTime = opts.clock.currentTimeNanosUnsafe().toString()
+  const eventMillis = options.date.getTime()
+  const eventTime = (BigInt(eventMillis) * nanosPerMilli).toString()
 
-  const attributes = OtlpResource.entriesToAttributes(Object.entries(options.fiber.getRef(CurrentLogAnnotations)))
-  attributes.push({
-    key: "fiberId",
-    value: { intValue: options.fiber.id }
-  })
+  const attributes: Record<string, unknown> = { ...options.fiber.getRef(CurrentLogAnnotations) }
+  attributes["effect.fiberId"] = options.fiber.id
   if (!opts.excludeLogSpans) {
+    // Outermost spans win duplicate labels.
     for (const [label, startTime] of options.fiber.getRef(CurrentLogSpans)) {
-      attributes.push({
-        key: `logSpan.${label}`,
-        value: { stringValue: `${nowMillis - startTime}ms` }
-      })
+      attributes[`effect.log_span.${label}`] = eventMillis - startTime
     }
   }
-  if (options.cause.reasons.length > 0) {
-    attributes.push({
-      key: "log.error",
-      value: { stringValue: Cause.pretty(options.cause) }
-    })
+  const errors = Cause.prettyErrors(options.cause, { includeCauseInStack: true })
+  if (errors.length > 0) {
+    attributes["exception.type"] = errors[0].name
+    attributes["exception.message"] = errors[0].message
+    attributes["exception.stacktrace"] = errors.map((error) => error.stack).join("\n")
   }
 
   const message = Arr.ensure(options.message)
 
   const logRecord: ILogRecord = {
     severityNumber: logLevelToSeverityNumber(options.logLevel),
     severityText: options.logLevel,
-    timeUnixNano: nanosString,
-    observedTimeUnixNano: nanosString,
-    attributes,
+    timeUnixNano: eventTime,
+    observedTimeUnixNano: observedTime,
+    attributes: OtlpResource.entriesToAttributes(Object.entries(attributes)),
     body: OtlpResource.unknownToAttributeValue(message.length === 1 ? message[0] : message),
     droppedAttributesCount: 0
   }

packages/effect/src/observability/OtlpResource.ts

@@ -13,6 +13,7 @@ import * as Config from "../Config.ts"
 import * as Effect from "../Effect.ts"
 import { format } from "../Formatter.ts"
 import * as Schema from "../Schema.ts"
+import * as Version from "../Version.ts"
 
 /**
  * OTLP resource metadata attached to exported logs, metrics, and traces.
@@ -28,46 +29,36 @@ export interface Resource {
   droppedAttributesCount: number
 }
 
+const isBrowser = "window" in globalThis || "importScripts" in globalThis
+
 /**
  * Creates an OTLP resource from service metadata and additional attributes.
  *
  * **Details**
  *
- * The resource always includes `service.name`, includes `service.version` when
- * provided, and converts custom attributes into OTLP attribute values.
+ * Adds `telemetry.sdk.*` defaults and converts custom attributes to OTLP values.
+ * Custom attributes override SDK defaults; service options override matching
+ * attributes. Omitted service options add no service attributes.
  *
  * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
 export const make = (options: {
-  readonly serviceName: string
+  readonly serviceName?: string | undefined
   readonly serviceVersion?: string | undefined
   readonly attributes?: Record<string, unknown> | undefined
-}): Resource => {
-  const resourceAttributes = options.attributes
-    ? entriesToAttributes(Object.entries(options.attributes))
-    : []
-  resourceAttributes.push({
-    key: "service.name",
-    value: {
-      stringValue: options.serviceName
-    }
-  })
-  if (options.serviceVersion) {
-    resourceAttributes.push({
-      key: "service.version",
-      value: {
-        stringValue: options.serviceVersion
-      }
-    })
-  }
-
-  return {
-    attributes: resourceAttributes,
-    droppedAttributesCount: 0
-  }
-}
+}): Resource => ({
+  attributes: entriesToAttributes(Object.entries({
+    "telemetry.sdk.name": "effect",
+    "telemetry.sdk.language": isBrowser ? "webjs" : "nodejs",
+    "telemetry.sdk.version": Version.getCurrentVersion(),
+    ...options.attributes,
+    ...(options.serviceName ? { "service.name": options.serviceName } : undefined),
+    ...(options.serviceVersion ? { "service.version": options.serviceVersion } : undefined)
+  })),
+  droppedAttributesCount: 0
+})
 
 /**
  * Creates an OTLP resource from explicit options and OpenTelemetry

packages/effect/src/observability/OtlpTracer.ts

@@ -26,6 +26,7 @@ import * as Option from "../Option.ts"
 import type * as Scope from "../Scope.ts"
 import * as Tracer from "../Tracer.ts"
 import type { ExtractTag } from "../Types.ts"
+import * as Version from "../Version.ts"
 import * as OtlpEnv from "./internal/otlpEnv.ts"
 import * as Exporter from "./OtlpExporter.ts"
 import type { KeyValue, Resource } from "./OtlpResource.ts"
@@ -67,7 +68,8 @@ export const make: (
   const otelResource = yield* OtlpResource.fromConfig(options.resource)
   const serialization = yield* OtlpSerialization
   const scope: Scope = {
-    name: OtlpResource.serviceNameUnsafe(otelResource)
+    name: "effect",
+    version: Version.getCurrentVersion()
   }
 
   const exporter = yield* Exporter.make({
@@ -413,6 +415,7 @@ export interface ScopeSpan {
 
 interface Scope {
   readonly name: string
+  readonly version?: string
 }
 
 interface OtlpSpan {

packages/effect/test/Version.test.ts

@@ -0,0 +1,17 @@
+import { assert, describe, it } from "@effect/vitest"
+import * as Version from "effect/Version"
+
+describe("Version", () => {
+  it("exposes a real version and supports isolated version overrides", () => {
+    const original = Version.getCurrentVersion()
+    assert.match(original, /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/)
+    assert.notStrictEqual(original, "0.0.0")
+    try {
+      Version.setCurrentVersion("test-version")
+      assert.strictEqual(Version.getCurrentVersion(), "test-version")
+    } finally {
+      Version.setCurrentVersion(original)
+    }
+    assert.strictEqual(Version.getCurrentVersion(), original)
+  })
+})

packages/effect/test/observability/OtlpExporter.test.ts

@@ -1,9 +1,9 @@
 import { assert, describe, it } from "@effect/vitest"
 import { Clock, ConfigProvider, Deferred, type Duration, Effect, Exit, Fiber, Layer, Metric, Ref, Scope } from "effect"
-import { HttpBody, HttpClient, HttpClientResponse } from "effect/http"
-import type { HttpClientError } from "effect/http"
+import { type Headers, HttpBody, HttpClient, type HttpClientError, HttpClientResponse } from "effect/http"
 import { OtlpExporter, OtlpLogger, OtlpMetrics, OtlpSerialization, OtlpTracer } from "effect/observability"
 import { TestClock } from "effect/testing"
+import * as Version from "effect/Version"
 
 const makeHttpClient = Effect.fnUntraced(function*(retryAfter: string | undefined) {
   const attempts = yield* Ref.make(0)
@@ -35,12 +35,13 @@ const makeExporter = (
     readonly maxBatchSize?: number | "disabled"
     readonly shutdownTimeout?: Duration.Input
     readonly body?: (data: Array<any>) => HttpBody.HttpBody
+    readonly headers?: Headers.Input | undefined
   }
 ) =>
   OtlpExporter.make({
     label: "OtlpExporterTest",
     url: "http://localhost:4318/v1/logs",
-    headers: undefined,
+    headers: options?.headers,
     exportInterval: options?.exportInterval ?? "1 hour",
     maxBatchSize: options?.maxBatchSize ?? 1,
     body: (data) => [options?.body?.(data) ?? HttpBody.empty, Effect.void],
@@ -107,6 +108,26 @@ const makeControlledHttpClient = Effect.fnUntraced(function*(requestCount: numbe
 })
 
 describe("OtlpExporter", () => {
+  it.effect("appends the versioned exporter User-Agent to a user-supplied value", () =>
+    Effect.gen(function*() {
+      const userAgents: Array<string> = []
+      const httpClient = HttpClient.makeWith(
+        Effect.fnUntraced(function*(requestEffect) {
+          const request = yield* requestEffect
+          userAgents.push(request.headers["user-agent"])
+          return HttpClientResponse.fromWeb(request, new Response())
+        }),
+        Effect.succeed as HttpClient.HttpClient.Preprocess<HttpClientError.HttpClientError, never>
+      )
+      yield* Effect.scoped(Effect.gen(function*() {
+        const exporter = yield* makeExporter(httpClient, { headers: { "UsEr-AgEnT": "my-app/1.0" }, maxBatchSize: 10 })
+        exporter.push({ value: 1 })
+      }))
+      assert.deepStrictEqual(userAgents, [
+        `my-app/1.0 OTel-OTLP-Exporter-JavaScript-Effect-OtlpExporterTest/${Version.getCurrentVersion()}`
+      ])
+    }))
+
   it.effect("allows an in-flight timer export to finish during shutdown", () =>
     Effect.gen(function*() {
       const scope = yield* Scope.make()