@alineo-labs/otel 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,43 @@
1
+ # @alineo-labs/otel
2
+
3
+ OpenTelemetry hooks adapter for [alineo](https://alineo.tech). Emits distributed traces for sandbox lifecycle events — sandbox creation, exec calls, and checkpoints.
4
+
5
+ ```bash
6
+ bun add @alineo-labs/otel
7
+ ```
8
+
9
+ ---
10
+
11
+ ## Usage
12
+
13
+ ```ts
14
+ import { otelHooks } from "@alineo-labs/otel";
15
+
16
+ const sb = await client.sandbox({
17
+ image: "ubuntu:22.04",
18
+ resources: { cpu: "500m", memory: "512Mi" },
19
+ hooks: otelHooks(tracer),
20
+ });
21
+ ```
22
+
23
+ ### Emitted spans
24
+
25
+ | Span | Emitted on |
26
+ | -------------------- | --------------------------- |
27
+ | `sandbox.run` | Sandbox created → closed |
28
+ | `sandbox.exec` | Each `sb.exec()` call |
29
+ | `sandbox.checkpoint` | Each `sb.checkpoint()` call |
30
+
31
+ ### Custom span options
32
+
33
+ ```ts
34
+ otelHooks(tracer, {
35
+ attributes: { "deployment.env": "production" },
36
+ });
37
+ ```
38
+
39
+ ---
40
+
41
+ ## License
42
+
43
+ Apache 2.0
@@ -0,0 +1,32 @@
1
+ import { Tracer } from "@opentelemetry/api";
2
+ import { SandboxHooks } from "@alineo-labs/core";
3
+
4
+ //#region src/index.d.ts
5
+ interface OtelHooksOptions {
6
+ /** Include exit code as a span attribute on exec spans. Default: true. */
7
+ recordExitCode?: boolean;
8
+ }
9
+ /**
10
+ * Returns `SandboxHooks` that emit OpenTelemetry traces for every sandbox run.
11
+ *
12
+ * Pass the result via the `hooks` field of `SandboxOptions` when calling `client.sandbox()`.
13
+ *
14
+ * Span structure:
15
+ * ```
16
+ * sandbox.run ← root span (sandboxId attribute)
17
+ * sandbox.exec ← child per exec (cmd, seq, exitCode unless recordExitCode: false)
18
+ * sandbox.checkpoint ← child per checkpoint (snapshotId)
19
+ * ```
20
+ *
21
+ * @example
22
+ * ```ts
23
+ * import { otelHooks } from "@alineo-labs/otel";
24
+ * import { trace } from "@opentelemetry/api";
25
+ *
26
+ * const tracer = trace.getTracer("my-app");
27
+ * const sb = await client.sandbox({ image: "node:22", resources: { cpu: "500m", memory: "256Mi" }, hooks: otelHooks(tracer) });
28
+ * ```
29
+ */
30
+ declare function otelHooks(tracer: Tracer, opts?: OtelHooksOptions): SandboxHooks;
31
+ //#endregion
32
+ export { OtelHooksOptions, otelHooks };
package/dist/index.mjs ADDED
@@ -0,0 +1,83 @@
1
+ import { SpanStatusCode, context, trace } from "@opentelemetry/api";
2
+ //#region src/index.ts
3
+ /**
4
+ * Returns `SandboxHooks` that emit OpenTelemetry traces for every sandbox run.
5
+ *
6
+ * Pass the result via the `hooks` field of `SandboxOptions` when calling `client.sandbox()`.
7
+ *
8
+ * Span structure:
9
+ * ```
10
+ * sandbox.run ← root span (sandboxId attribute)
11
+ * sandbox.exec ← child per exec (cmd, seq, exitCode unless recordExitCode: false)
12
+ * sandbox.checkpoint ← child per checkpoint (snapshotId)
13
+ * ```
14
+ *
15
+ * @example
16
+ * ```ts
17
+ * import { otelHooks } from "@alineo-labs/otel";
18
+ * import { trace } from "@opentelemetry/api";
19
+ *
20
+ * const tracer = trace.getTracer("my-app");
21
+ * const sb = await client.sandbox({ image: "node:22", resources: { cpu: "500m", memory: "256Mi" }, hooks: otelHooks(tracer) });
22
+ * ```
23
+ */
24
+ function otelHooks(tracer, opts = {}) {
25
+ const { recordExitCode = true } = opts;
26
+ let rootSpan;
27
+ let rootCtx;
28
+ const execSpans = /* @__PURE__ */ new Map();
29
+ return {
30
+ onSandboxCreated(sandboxId, name) {
31
+ rootCtx = context.active();
32
+ rootSpan = tracer.startSpan("sandbox.run", { attributes: {
33
+ "alineo.sandbox.id": sandboxId,
34
+ "alineo.sandbox.name": name
35
+ } }, rootCtx);
36
+ },
37
+ onExecStart(sandboxId, seq, cmd) {
38
+ if (!rootSpan || !rootCtx) return;
39
+ const spanCtx = trace.setSpan(rootCtx, rootSpan);
40
+ const span = tracer.startSpan("sandbox.exec", { attributes: {
41
+ "alineo.sandbox.id": sandboxId,
42
+ "alineo.exec.seq": seq,
43
+ "alineo.exec.cmd": cmd
44
+ } }, spanCtx);
45
+ execSpans.set(seq, span);
46
+ },
47
+ onExecComplete(_sandboxId, seq, result) {
48
+ const span = execSpans.get(seq);
49
+ if (!span) return;
50
+ if (recordExitCode) span.setAttribute("process.exit_code", result.exitCode);
51
+ span.setStatus({ code: result.exitCode === 0 ? SpanStatusCode.OK : SpanStatusCode.ERROR });
52
+ span.end();
53
+ execSpans.delete(seq);
54
+ },
55
+ onCheckpoint(sandboxId, snapshotId, name) {
56
+ if (!rootSpan || !rootCtx) return;
57
+ const spanCtx = trace.setSpan(rootCtx, rootSpan);
58
+ const span = tracer.startSpan("sandbox.checkpoint", { attributes: {
59
+ "alineo.sandbox.id": sandboxId,
60
+ "alineo.snapshot.id": snapshotId,
61
+ ...name ? { "alineo.checkpoint.name": name } : {}
62
+ } }, spanCtx);
63
+ span.setStatus({ code: SpanStatusCode.OK });
64
+ span.end();
65
+ },
66
+ onSandboxClosed(_sandboxId) {
67
+ rootSpan?.setStatus({ code: SpanStatusCode.OK });
68
+ rootSpan?.end();
69
+ rootSpan = void 0;
70
+ },
71
+ onSandboxFailed(_sandboxId, error) {
72
+ rootSpan?.recordException(error);
73
+ rootSpan?.setStatus({
74
+ code: SpanStatusCode.ERROR,
75
+ message: error.message
76
+ });
77
+ rootSpan?.end();
78
+ rootSpan = void 0;
79
+ }
80
+ };
81
+ }
82
+ //#endregion
83
+ export { otelHooks };
package/package.json ADDED
@@ -0,0 +1,41 @@
1
+ {
2
+ "name": "@alineo-labs/otel",
3
+ "version": "0.1.0",
4
+ "license": "Apache-2.0",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "git+https://github.com/DrejT/alineo.git",
8
+ "directory": "packages/adapters/otel"
9
+ },
10
+ "files": [
11
+ "dist"
12
+ ],
13
+ "type": "module",
14
+ "main": "./dist/index.mjs",
15
+ "types": "./dist/index.d.mts",
16
+ "exports": {
17
+ ".": {
18
+ "import": "./dist/index.mjs",
19
+ "types": "./dist/index.d.mts"
20
+ }
21
+ },
22
+ "publishConfig": {
23
+ "access": "public",
24
+ "provenance": true
25
+ },
26
+ "scripts": {
27
+ "build": "tsdown"
28
+ },
29
+ "dependencies": {
30
+ "@alineo-labs/core": "0.1.0"
31
+ },
32
+ "devDependencies": {
33
+ "@opentelemetry/api": "1.9.1",
34
+ "bun-types": "1.3.14",
35
+ "tsdown": "0.22.3",
36
+ "typescript": "6.0.3"
37
+ },
38
+ "peerDependencies": {
39
+ "@opentelemetry/api": "^1.0.0"
40
+ }
41
+ }