@afora/otel 0.0.0-stage → 0.0.11

package/README.md

@@ -1,3 +1,58 @@
-# Temporary Holding Version
+# @afora/otel
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[OpenTelemetry](https://opentelemetry.io) tracing for [`@afora/core`](../../README.md) applications: a span per command operation, use case and repository call made through a use case, nested as the calls are, with the exception layer and name on failure and no input, response or sensitive value in any span. What the spans are and carry is in [docs/tracing.md](../../docs/tracing.md).
+
+```bash
+bun add @afora/core @afora/otel @opentelemetry/api
+```
+
+`@afora/core` and `@opentelemetry/api` (`^1.9.0`) are peer dependencies. Set up an OpenTelemetry SDK as usual (`@opentelemetry/sdk-node`, an exporter); the package itself uses only the API, so it runs on Bun, Node >= 22 and Workers.
+
+## Example
+
+<!-- docs:code skip: Post, Posts, Blog and Api are the declarations of your application -->
+```ts
+import { applicationOf } from "@afora/core";
+import { otelTracer } from "@afora/otel";
+
+export const App = applicationOf({
+	name: "blog",
+	entities: { Post },
+	repositories: { Posts },
+	commands: { Blog },
+	outputs: { Api },
+	trace: otelTracer(),
+});
+```
+
+A request to `App.outputs.Api.build()`, on Hono or any HTTP sink, gives one trace:
+
+```
+command Blog.publish          afora.command=Blog.publish afora.operation=publish afora.outcome=ok
+└─ use-case Publish           afora.use_case=Publish afora.outcome=ok
+   └─ repository Post.create  afora.repository=Post afora.method=create afora.use_case=Publish
+```
+
+## API
+
+- **`otelTracer(tracer?)`**: the `ITracer` of `@afora/core` over an OpenTelemetry `Tracer`, by default `trace.getTracer(AFORA_TRACER_NAME)` of the global tracer provider (it works before the SDK registers, as OpenTelemetry tracers do).
+  - A command span is a child of the active span, such as the server span of your HTTP instrumentation; the spans below it are children of their caller's span whether or not a context manager is registered.
+  - With a context manager, each call runs with its span active, so the spans your code and instrumented drivers start inside a use case or a repository call nest in it.
+  - A failed span has the status `ERROR`, with the exception name as its message, and the attributes `afora.exception.layer`, `afora.exception.name` and `afora.exception.unexpected`; no exception event is recorded, since the message and stack of an error can hold values. A span that succeeded keeps the status unset.
+- **`AFORA_TRACER_NAME`**: `"@afora/otel"`, the instrumentation scope of the default tracer.
+
+## In an afora.json
+
+```json
+{ "version": 1, "name": "blog", "trace": { "import": "../trace.ts#tracer" } }
+```
+
+with `export const tracer = otelTracer();` in `trace.ts` (see [afora.json](../../docs/afora-json.md#tracing)).
+
+## Tests
+
+```bash
+bun run test:otel  # from the repository root
+```
+
+The tests serve an application through [`@afora/hono`](../hono/README.md) with an in-memory span exporter, and check the trace of a request (command, use cases, repository calls), the attributes of a failure, and that no password, hash, input or id reaches any span.

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import type { ITracer } from "@afora/core";
+import { type Tracer } from "@opentelemetry/api";
+/** The instrumentation scope of the default tracer. */
+export declare const AFORA_TRACER_NAME = "@afora/otel";
+/**
+ * The `trace` of an application, over an OpenTelemetry `Tracer` (by default
+ * `trace.getTracer("@afora/otel")`, of the global tracer provider):
+ *
+ * ```ts
+ * applicationOf({ name: "blog", trace: otelTracer(), ... });
+ * ```
+ *
+ * A command span is a child of the active span (an HTTP server span of your
+ * instrumentation, say); a use case span a child of its command or of the use
+ * case that ran it; a repository span a child of its use case, whether or not
+ * a context manager is registered. With one, each call also runs with its
+ * span active, so the spans of your code and of instrumented drivers nest in it.
+ */
+export declare function otelTracer(tracer?: Tracer): ITracer;

package/dist/index.js

@@ -0,0 +1,40 @@
+// src/index.ts
+import {
+  context,
+  SpanStatusCode,
+  trace
+} from "@opentelemetry/api";
+var AFORA_TRACER_NAME = "@afora/otel";
+
+class OtelSpan {
+  span;
+  constructor(span) {
+    this.span = span;
+  }
+  end(status, attributes) {
+    this.span.setAttributes(attributes);
+    if (status === "error") {
+      const name = attributes["afora.exception.name"];
+      this.span.setStatus({
+        code: SpanStatusCode.ERROR,
+        ...typeof name === "string" ? { message: name } : {}
+      });
+    }
+    this.span.end();
+  }
+}
+function otelTracer(tracer = trace.getTracer(AFORA_TRACER_NAME)) {
+  return Object.freeze({
+    startSpan(name, attributes, parent) {
+      const active = context.active();
+      return new OtelSpan(tracer.startSpan(name, { attributes }, parent instanceof OtelSpan ? trace.setSpan(active, parent.span) : active));
+    },
+    withSpan(span, run) {
+      return span instanceof OtelSpan ? context.with(trace.setSpan(context.active(), span.span), run) : run();
+    }
+  });
+}
+export {
+  AFORA_TRACER_NAME,
+  otelTracer
+};

package/package.json

@@ -1,6 +1,60 @@
 {
-  "name": "@afora/otel",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@afora/otel",
+	"version": "0.0.11",
+	"description": "OpenTelemetry tracing for afora applications: a span per command, use case and repository call, nested as the calls are, with no input, response or sensitive value in any span.",
+	"keywords": [
+		"afora",
+		"opentelemetry",
+		"otel",
+		"tracing",
+		"observability"
+	],
+	"author": "Alan Reis <alanreisanjo@gmail.com> (https://github.com/Hoyasumii)",
+	"license": "MIT",
+	"homepage": "https://github.com/afora-framework/core/tree/main/packages/otel#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/afora-framework/core.git",
+		"directory": "packages/otel"
+	},
+	"type": "module",
+	"main": "./dist/index.js",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"files": [
+		"dist"
+	],
+	"engines": {
+		"bun": ">=1.4.4",
+		"node": ">=22"
+	},
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	},
+	"scripts": {
+		"typecheck": "bun check",
+		"build": "rm -rf dist && bun build ./src/index.ts --outdir ./dist --target node --format esm --packages external --tsconfig-override tsconfig.build.json && tsc -p tsconfig.build.json && bun ../../scripts/add-dts-extensions.ts dist",
+		"test": "bun test"
+	},
+	"devDependencies": {
+		"@afora/hono": "workspace:*",
+		"@opentelemetry/api": "^1.9.0",
+		"@opentelemetry/context-async-hooks": "^2.2.0",
+		"@opentelemetry/sdk-trace-base": "^2.2.0",
+		"@types/bun": "^1.4.4",
+		"hono": "^4.13.14"
+	},
+	"peerDependencies": {
+		"@afora/core": ">=0.0.11",
+		"@opentelemetry/api": "^1.9.0"
+	}
+}