@kittl/observability-node 0.1.0

package/README.md

@@ -0,0 +1,174 @@
+# Node Observability
+
+Shared Node.js observability for Kittl services and workers.
+
+`@kittl/observability-node` provides a single entry point for OpenTelemetry tracing and metrics.
+
+## How to use
+
+Create `telemetry.ts` file and make sure it is imported into your entrypoint:
+
+```typescript
+import { KittlNodeTelemetry } from '@kittl/observability-node';
+
+const telemetry = new KittlNodeTelemetry({
+  serviceName: 'api',
+  serviceVersion: process.env.RELEASE_SHA,
+  owner: 'developers',
+});
+telemetry.start();
+```
+
+With default parameters this sets up Node auto-instrumentation and exports both metrics and traces. Metrics will be exposed on port `9464` under `/metrics` path by default. If you use `@kittl/logger`, logs will be correlated with traces automatically.
+
+It is recommended to shut down the instance gracefully based on `SIGTERM` signal:
+
+```typescript
+process.on('SIGTERM', () => {
+  telemetry
+    .shutdown()
+    .then(
+      () => logger.info('SDK shut down successfully'),
+      (err) => logger.error('Error shutting down SDK', err)
+    )
+    .finally(() => process.exit(0));
+});
+```
+
+Node auto-instrumentations can be fine-tuned using `nodeAutoInstrumentations` parameter:
+
+```typescript
+new KittlNodeTelemetry({
+  serviceName: 'api',
+  nodeAutoInstrumentations: {
+    '@opentelemetry/instrumentation-express': {
+      ignoreLayersType: [ExpressLayerType.MIDDLEWARE, ExpressLayerType.ROUTER],
+    },
+  },
+});
+```
+
+NOTE: For each auto instrumentation configuration, only specified parameters will be overridden. Remaining parameters will be set to default values.
+
+> Check [supported-instrumentations](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/packages/) for information on what is included.
+
+Additional instrumentations can be added via `additionalInstrumentations` parameter:
+
+```typescript
+import { PrismaInstrumentation } from '@prisma/instrumentation';
+
+new KittlNodeTelemetry({
+  serviceName: 'api',
+  additionalInstrumentations: [new PrismaInstrumentation()],
+});
+```
+
+## Kubernetes configuration
+
+To make sure that service metrics are collected and traces are exported, following minimal `values.yaml` configuration is required:
+
+```yaml
+env:
+  - name: NODE_IP
+    valueFrom:
+      fieldRef:
+        fieldPath: status.hostIP
+  - name: OTEL_EXPORTER_OTLP_ENDPOINT
+    value: http://$(NODE_IP):4318
+deployment:
+  metrics:
+    enabled: true
+    port: 9464 # change if different port is used
+    path: /metrics
+```
+
+In addition following environment variables are recommended to be set via configmap:
+
+```yaml
+OTEL_LOG_LEVEL: warn
+# use new stable HTTP conventions
+OTEL_SEMCONV_STABILITY_OPT_IN: http
+```
+
+## User journeys
+
+This package provides abstraction for tracking user journeys in a standardized way via `Journey` class. It supports recording step transitions as a counter metric, as well as recording step durations into a histogram.
+
+Steps are particular operations inside the journey. For example, AI generation journey might contain separate steps to charge the user, generate image and refund the user in case of error. Each step has a particular outcome - for example, generation might fail with an error, be successful or it might time out. For more information on this topic see [Business Metrics Taxonomy](https://app.notion.com/p/kittl/Business-Metrics-Taxonomy-35985ae43d478142bd1fef4b5e86a02b)
+
+Here's an example of tracking `generation` step in `ai_generation` journey using `recordStep` method:
+
+```typescript
+import { Journey, ATTR_OUTCOME, ATTR_ERROR_CATEGORY } from '@kittl/observability-node';
+
+const aiGenerationJourney = new Journey('ai_generation');
+
+function generateAiImage(...) {
+  try {
+    /** some business logic */
+  } catch {
+    aiGenerationJourney.recordStep('generation', {
+      [ATTR_OUTCOME]: 'failure',
+      [ATTR_ERROR_CATEGORY]: 'generation_failed',
+    });
+    return;
+  }
+  aiGenerationJourney.recordStep('generation', {
+    [ATTR_OUTCOME]: 'success',
+  });
+}
+```
+
+> NOTE: Error category is always tracked, but defaults to `none` when it is not specified.
+
+By default `Journey` only allows passing built-in `ATTR_OUTCOME` and `ATTR_ERROR_CATEGORY` attributes. To include additional attributes, they should be fined as an `interface` and passed to `Journey` as a generic type argument:
+
+```typescript
+import { ATTR_PROVIDER } from '@kittl/observability-node';
+
+const ATTR_CONTENT_TYPE = 'content.type';
+
+interface AiGenerationJourneyAttributes {
+  [ATTR_PROVIDER]?: 'nano-banana' | 'gemini' | 'stripe';
+  [ATTR_CONTENT_TYPE]?: 'image' | 'video';
+}
+
+const aiGenerationJourney = new Journey<AiGenerationJourneyAttributes>(
+  'ai_generation'
+);
+aiGenerationJourney.recordStep('generation', {
+  [ATTR_OUTCOME]: 'success',
+  [ATTR_PROVIDER]: 'nano-banana',
+  [ATTR_CONTENT_TYPE]: 'image',
+});
+```
+
+In cases where we are also interested in duration of a step, it is possible to also track step duration via `recordStepWithDuration` method. It does same as what `recordStep` does, but also records duration measurement in a histogram. Here's an example of tracking a different step in `ai_generation` journey:
+
+```typescript
+function chargeUserForGeneration(...) {
+  const startTime = performance.now();
+  /** some business logic */
+  aiGenerationJourney.recordStepWithDuration(
+    'charge',
+    (performance.now() - startTime) / 1000, // convert to seconds
+    {
+      [ATTR_OUTCOME]: 'success',
+      [ATTR_PROVIDER]: 'stripe'
+    }
+  ),
+}
+```
+
+> NOTE: This example omits error handling for simplicity, but it is necessary when tracking durations in production code.
+
+As this pattern of tracking start time and subtracting it from current time is so common, `Journey` class provides a useful `createTimer` method to simplify it:
+
+```typescript
+const timer = aiGenerationJourney.createTimer();
+/** some businees logic */
+timer.recordStepWithDuration('charge', {
+  [ATTR_OUTCOME]: 'success',
+  [ATTR_PROVIDER]: 'stripe',
+});
+```

package/dist/conventions.d.ts

@@ -0,0 +1,42 @@
+/** Owner of the service. */
+export declare const ATTR_OWNER = "owner";
+/** Name of the journey. */
+export declare const ATTR_JOURNEY = "journey";
+/** Name of the journey step. */
+export declare const ATTR_STEP = "step";
+/** Journey step outcome. */
+export declare const ATTR_OUTCOME = "outcome";
+/** Step completed as expected. */
+export declare const OUTCOME_VALUE_SUCCESS = "success";
+/** Unexpected technical or dependency failure. */
+export declare const OUTCOME_VALUE_FAILURE = "failure";
+/** Expected product/business block */
+export declare const OUTCOME_VALUE_BLOCKED = "blocked";
+/** Step exceeded the defined completion window. */
+export declare const OUTCOME_VALUE_TIMEOUT = "timeout";
+/** User or system explicitly cancelled the operation */
+export declare const OUTCOME_VALUE_CANCELLED = "cancelled";
+/**
+ * User left/cancelled before completion and this is observable.
+ *
+ * Use only when the client/RUM path can observe abandonment;
+ * do not infer per-user abandonment from missing backend completion alone.
+ */
+export declare const OUTCOME_VALUE_ABANDONED = "abandoned";
+/** Temporary fallback when classification is missing. */
+export declare const OUTCOME_VALUE_UNKNOWN = "unknown";
+export type OutcomeValue = typeof OUTCOME_VALUE_SUCCESS | typeof OUTCOME_VALUE_FAILURE | typeof OUTCOME_VALUE_BLOCKED | typeof OUTCOME_VALUE_TIMEOUT | typeof OUTCOME_VALUE_CANCELLED | typeof OUTCOME_VALUE_ABANDONED | typeof OUTCOME_VALUE_UNKNOWN;
+/** Journey step error category. */
+export declare const ATTR_ERROR_CATEGORY = "error.category";
+/** Use for successful outcomes. */
+export declare const ERROR_CATEGORY_VALUE_NONE = "none";
+/** User-facing surface where the journey step is happening. */
+export declare const ATTR_SURFACE = "surface";
+/** Subcomponent which is responsible for the journey step. */
+export declare const ATTR_COMPONENT = "component";
+/** External provider which is responsible for the journey step. */
+export declare const ATTR_PROVIDER = "provider";
+/** Bounded dependency being called. */
+export declare const ATTR_DEPENDENCY = "dependency";
+/** General fallback for undefined and null values. */
+export declare const VALUE_UNKNOWN = "unknown";

package/dist/conventions.js

@@ -0,0 +1,46 @@
+"use strict";
+// Resource attribute conventions.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VALUE_UNKNOWN = exports.ATTR_DEPENDENCY = exports.ATTR_PROVIDER = exports.ATTR_COMPONENT = exports.ATTR_SURFACE = exports.ERROR_CATEGORY_VALUE_NONE = exports.ATTR_ERROR_CATEGORY = exports.OUTCOME_VALUE_UNKNOWN = exports.OUTCOME_VALUE_ABANDONED = exports.OUTCOME_VALUE_CANCELLED = exports.OUTCOME_VALUE_TIMEOUT = exports.OUTCOME_VALUE_BLOCKED = exports.OUTCOME_VALUE_FAILURE = exports.OUTCOME_VALUE_SUCCESS = exports.ATTR_OUTCOME = exports.ATTR_STEP = exports.ATTR_JOURNEY = exports.ATTR_OWNER = void 0;
+/** Owner of the service. */
+exports.ATTR_OWNER = 'owner';
+// Journey metric attribute conventions.
+/** Name of the journey. */
+exports.ATTR_JOURNEY = 'journey';
+/** Name of the journey step. */
+exports.ATTR_STEP = 'step';
+/** Journey step outcome. */
+exports.ATTR_OUTCOME = 'outcome';
+/** Step completed as expected. */
+exports.OUTCOME_VALUE_SUCCESS = 'success';
+/** Unexpected technical or dependency failure. */
+exports.OUTCOME_VALUE_FAILURE = 'failure';
+/** Expected product/business block */
+exports.OUTCOME_VALUE_BLOCKED = 'blocked';
+/** Step exceeded the defined completion window. */
+exports.OUTCOME_VALUE_TIMEOUT = 'timeout';
+/** User or system explicitly cancelled the operation */
+exports.OUTCOME_VALUE_CANCELLED = 'cancelled';
+/**
+ * User left/cancelled before completion and this is observable.
+ *
+ * Use only when the client/RUM path can observe abandonment;
+ * do not infer per-user abandonment from missing backend completion alone.
+ */
+exports.OUTCOME_VALUE_ABANDONED = 'abandoned';
+/** Temporary fallback when classification is missing. */
+exports.OUTCOME_VALUE_UNKNOWN = 'unknown';
+/** Journey step error category. */
+exports.ATTR_ERROR_CATEGORY = 'error.category';
+/** Use for successful outcomes. */
+exports.ERROR_CATEGORY_VALUE_NONE = 'none';
+/** User-facing surface where the journey step is happening. */
+exports.ATTR_SURFACE = 'surface';
+/** Subcomponent which is responsible for the journey step. */
+exports.ATTR_COMPONENT = 'component';
+/** External provider which is responsible for the journey step. */
+exports.ATTR_PROVIDER = 'provider';
+/** Bounded dependency being called. */
+exports.ATTR_DEPENDENCY = 'dependency';
+/** General fallback for undefined and null values. */
+exports.VALUE_UNKNOWN = 'unknown';

package/dist/helpers/dropNullUndefinedEntries.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Filters out null/undefined values from an object.
+ * @param object - Object to filter.
+ * @returns New object with null/undefined values removed.
+ */
+export declare function dropNullUndefinedEntries<T extends object>(object: T): T;

package/dist/helpers/dropNullUndefinedEntries.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dropNullUndefinedEntries = dropNullUndefinedEntries;
+/**
+ * Filters out null/undefined values from an object.
+ * @param object - Object to filter.
+ * @returns New object with null/undefined values removed.
+ */
+function dropNullUndefinedEntries(object) {
+    return Object.fromEntries(Object.entries(object).filter(([, value]) => value != null));
+}

package/dist/helpers/singleton.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Implements a singleton pattern, initializing the instance only when it is accessed for the first time.
+ * @param create - A function that creates the instance.
+ * @returns Function to get the singleton instance.
+ */
+export default function singleton<T>(create: () => T): () => T;

package/dist/helpers/singleton.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = singleton;
+/**
+ * Implements a singleton pattern, initializing the instance only when it is accessed for the first time.
+ * @param create - A function that creates the instance.
+ * @returns Function to get the singleton instance.
+ */
+function singleton(create) {
+    let instance = null;
+    return () => {
+        if (!instance) {
+            instance = create();
+        }
+        return instance;
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './conventions';
+export { Journey } from './journey';
+export { KittlNodeTelemetry } from './telemetry';

package/dist/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KittlNodeTelemetry = exports.Journey = void 0;
+__exportStar(require("./conventions"), exports);
+var journey_1 = require("./journey");
+Object.defineProperty(exports, "Journey", { enumerable: true, get: function () { return journey_1.Journey; } });
+var telemetry_1 = require("./telemetry");
+Object.defineProperty(exports, "KittlNodeTelemetry", { enumerable: true, get: function () { return telemetry_1.KittlNodeTelemetry; } });

package/dist/journey.d.ts

@@ -0,0 +1,33 @@
+import { ATTR_ERROR_CATEGORY, ATTR_OUTCOME, type OutcomeValue } from './conventions';
+type BaseJourneyAttributes = {
+    [ATTR_OUTCOME]: OutcomeValue;
+    [ATTR_ERROR_CATEGORY]?: string;
+};
+interface JourneyTimer<TAttributes> {
+    recordStepWithDuration(step: string, attributes: TAttributes): void;
+}
+/** Manages metrics for a specific journey. */
+export declare class Journey<TAttributes extends object = BaseJourneyAttributes> {
+    private readonly name;
+    constructor(name: string);
+    /**
+     * Record transition for a particular step in the journey.
+     * @param step - The name of the step.
+     * @param attributes - Additional attributes to add to the metric.
+     */
+    recordStep(step: string, attributes: TAttributes & BaseJourneyAttributes): void;
+    /**
+     * Record transition for a particular step in the journey, along with its duration.
+     * @param step - The name of the step.
+     * @param durationSeconds - How long the step took in seconds.
+     * @param attributes - Additional attributes to add to the metric.
+     */
+    recordStepWithDuration(step: string, durationSeconds: number, attributes: TAttributes & BaseJourneyAttributes): void;
+    /**
+     * Helper to automatically time elapsed duration and record it in the appropriate metric.
+     * @returns A timer object that is automatically started.
+     */
+    createTimer(): JourneyTimer<TAttributes & BaseJourneyAttributes>;
+    private normalizeStepAttributes;
+}
+export {};

package/dist/journey.js

@@ -0,0 +1,80 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Journey = void 0;
+const api_1 = require("@opentelemetry/api");
+const conventions_1 = require("./conventions");
+const dropNullUndefinedEntries_1 = require("./helpers/dropNullUndefinedEntries");
+const singleton_1 = __importDefault(require("./helpers/singleton"));
+const logger_1 = require("./logger");
+const log = logger_1.logger.child('journeys');
+// Lazy initialize metrics to make sure that SDK is started before we use them
+const getJourneysMeter = (0, singleton_1.default)(() => api_1.metrics.getMeter('kittl.journeys'));
+const getJourneyStepCounter = (0, singleton_1.default)(() => getJourneysMeter().createCounter('journey.step', {
+    description: 'Count of journey step transitions',
+    unit: '{event}',
+}));
+const getJourneyStepDurationHistogram = (0, singleton_1.default)(() => getJourneysMeter().createHistogram('journey.step.duration', {
+    description: 'Journey step durations',
+    unit: 's',
+    advice: {
+        explicitBucketBoundaries: [
+            0.1, 0.25, 0.5, 1, 2, 5, 10, 30, 60, 120, 300, 600, 1200,
+        ],
+    },
+}));
+/** Manages metrics for a specific journey. */
+class Journey {
+    constructor(name) {
+        this.name = name;
+    }
+    /**
+     * Record transition for a particular step in the journey.
+     * @param step - The name of the step.
+     * @param attributes - Additional attributes to add to the metric.
+     */
+    recordStep(step, attributes) {
+        getJourneyStepCounter().add(1, this.normalizeStepAttributes(step, attributes));
+    }
+    /**
+     * Record transition for a particular step in the journey, along with its duration.
+     * @param step - The name of the step.
+     * @param durationSeconds - How long the step took in seconds.
+     * @param attributes - Additional attributes to add to the metric.
+     */
+    recordStepWithDuration(step, durationSeconds, attributes) {
+        if (durationSeconds < 0 || !Number.isFinite(durationSeconds)) {
+            log.error('Error recording journey step duration', new Error('Invalid duration provided'), {
+                durationSeconds,
+                journey: this.name,
+                step,
+            });
+            return;
+        }
+        this.recordStep(step, attributes);
+        getJourneyStepDurationHistogram().record(durationSeconds, this.normalizeStepAttributes(step, attributes));
+    }
+    /**
+     * Helper to automatically time elapsed duration and record it in the appropriate metric.
+     * @returns A timer object that is automatically started.
+     */
+    createTimer() {
+        const start = performance.now();
+        const getDuration = () => (performance.now() - start) / 1000;
+        return {
+            recordStepWithDuration: (step, attributes) => this.recordStepWithDuration(step, getDuration(), attributes),
+        };
+    }
+    normalizeStepAttributes(step, attributes) {
+        return {
+            ...(0, dropNullUndefinedEntries_1.dropNullUndefinedEntries)(attributes),
+            [conventions_1.ATTR_JOURNEY]: this.name,
+            [conventions_1.ATTR_STEP]: step,
+            // error category should always be present
+            [conventions_1.ATTR_ERROR_CATEGORY]: attributes[conventions_1.ATTR_ERROR_CATEGORY] ?? conventions_1.ERROR_CATEGORY_VALUE_NONE,
+        };
+    }
+}
+exports.Journey = Journey;

package/dist/logger.d.ts

@@ -0,0 +1,2 @@
+import { ApiLogger } from '@repo/logger';
+export declare const logger: ApiLogger;

package/dist/logger.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+const logger_1 = require("@repo/logger");
+exports.logger = new logger_1.ApiLogger();

package/dist/telemetry.d.ts

@@ -0,0 +1,31 @@
+import { type InstrumentationConfigMap } from '@opentelemetry/auto-instrumentations-node';
+import type { Instrumentation } from '@opentelemetry/instrumentation';
+import { NodeSDK, type NodeSDKConfiguration } from '@opentelemetry/sdk-node';
+interface KittlNodeTelemetryOptions {
+    serviceName: string;
+    serviceVersion?: string;
+    owner?: string;
+    metricsEnabled?: boolean;
+    tracesEnabled?: boolean;
+    metricsPort?: number;
+    nodeAutoInstrumentations?: InstrumentationConfigMap;
+    additionalInstrumentations?: Instrumentation[];
+}
+export declare class KittlNodeTelemetry {
+    readonly sdk: NodeSDK;
+    /**
+     * @param options.serviceName - The name of the service (required).
+     * @param options.serviceVersion - The version of the service (optional).
+     * @param options.owner - The owner of the service (optional).
+     * @param options.metricsEnabled - Whether to enable metrics (default: true).
+     * @param options.tracesEnabled - Whether to enable tracing (default: true).
+     * @param options.metricsPort - The port to use for the metrics exporter (default: 9464).
+     * @param options.nodeAutoInstrumentations - Override the default auto-instrumentations.
+     * @param options.additionalInstrumentations - Additional instrumentations to add to the SDK.
+     */
+    constructor(options: KittlNodeTelemetryOptions);
+    instantiateSdk(config: Partial<NodeSDKConfiguration>): NodeSDK;
+    start(): void;
+    shutdown(): Promise<void>;
+}
+export {};

package/dist/telemetry.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KittlNodeTelemetry = void 0;
+const auto_instrumentations_node_1 = require("@opentelemetry/auto-instrumentations-node");
+const exporter_prometheus_1 = require("@opentelemetry/exporter-prometheus");
+const exporter_trace_otlp_http_1 = require("@opentelemetry/exporter-trace-otlp-http");
+const instrumentation_express_1 = require("@opentelemetry/instrumentation-express");
+const resources_1 = require("@opentelemetry/resources");
+const sdk_node_1 = require("@opentelemetry/sdk-node");
+const semantic_conventions_1 = require("@opentelemetry/semantic-conventions");
+const conventions_1 = require("./conventions");
+class KittlNodeTelemetry {
+    /**
+     * @param options.serviceName - The name of the service (required).
+     * @param options.serviceVersion - The version of the service (optional).
+     * @param options.owner - The owner of the service (optional).
+     * @param options.metricsEnabled - Whether to enable metrics (default: true).
+     * @param options.tracesEnabled - Whether to enable tracing (default: true).
+     * @param options.metricsPort - The port to use for the metrics exporter (default: 9464).
+     * @param options.nodeAutoInstrumentations - Override the default auto-instrumentations.
+     * @param options.additionalInstrumentations - Additional instrumentations to add to the SDK.
+     */
+    constructor(options) {
+        const autoInstrumentations = options?.nodeAutoInstrumentations ?? {};
+        this.sdk = this.instantiateSdk({
+            resource: (0, resources_1.resourceFromAttributes)({
+                [semantic_conventions_1.ATTR_SERVICE_NAME]: options.serviceName,
+                [semantic_conventions_1.ATTR_SERVICE_VERSION]: options.serviceVersion,
+                [conventions_1.ATTR_OWNER]: options.owner,
+            }),
+            traceExporter: options?.tracesEnabled === false ? undefined : new exporter_trace_otlp_http_1.OTLPTraceExporter(),
+            metricReader: options?.metricsEnabled === false
+                ? undefined
+                : new exporter_prometheus_1.PrometheusExporter({ port: options?.metricsPort }),
+            instrumentations: [
+                (0, auto_instrumentations_node_1.getNodeAutoInstrumentations)({
+                    ...autoInstrumentations,
+                    // These instrumentations are disabled as they don't provide much value and add a lot of noise
+                    '@opentelemetry/instrumentation-dns': {
+                        enabled: false,
+                        ...autoInstrumentations['@opentelemetry/instrumentation-dns'],
+                    },
+                    '@opentelemetry/instrumentation-connect': {
+                        enabled: false,
+                        ...autoInstrumentations['@opentelemetry/instrumentation-connect'],
+                    },
+                    '@opentelemetry/instrumentation-net': {
+                        enabled: false,
+                        ...autoInstrumentations['@opentelemetry/instrumentation-net'],
+                    },
+                    '@opentelemetry/instrumentation-express': {
+                        // These layers are disabled as they don't provide much value and add a lot of noise
+                        ignoreLayersType: [
+                            instrumentation_express_1.ExpressLayerType.MIDDLEWARE,
+                            instrumentation_express_1.ExpressLayerType.ROUTER,
+                        ],
+                        ...autoInstrumentations['@opentelemetry/instrumentation-express'],
+                    },
+                    '@opentelemetry/instrumentation-pino': {
+                        // Use camelCase log keys to match other log attributes.
+                        logKeys: {
+                            traceId: 'traceId',
+                            spanId: 'spanId',
+                            traceFlags: 'traceFlags',
+                        },
+                        ...autoInstrumentations['@opentelemetry/instrumentation-pino'],
+                    },
+                }),
+                ...(options?.additionalInstrumentations ?? []),
+            ],
+        });
+    }
+    instantiateSdk(config) {
+        return new sdk_node_1.NodeSDK(config);
+    }
+    start() {
+        this.sdk.start();
+    }
+    shutdown() {
+        return this.sdk.shutdown();
+    }
+}
+exports.KittlNodeTelemetry = KittlNodeTelemetry;

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@kittl/observability-node",
+  "version": "0.1.0",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "lint:biome": "biome check ./src --error-on-warnings --no-errors-on-unmatched",
+    "lint": "pnpm run lint:biome",
+    "lint:fix": "pnpm run lint:biome --write",
+    "test": "tsx --test",
+    "verify:types": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@repo/biome-config": "workspace:*",
+    "@repo/typescript-config": "workspace:*",
+    "tsx": "4.19.2"
+  },
+  "lint-staged": {
+    "**/*.{ts,tsx,js,jsx,json}": [
+      "biome check --write --error-on-warnings --no-errors-on-unmatched"
+    ]
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/auto-instrumentations-node": "0.75.0",
+    "@opentelemetry/exporter-prometheus": "0.217.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.202.0",
+    "@opentelemetry/instrumentation": "0.217.0",
+    "@opentelemetry/instrumentation-express": "^0.51.0",
+    "@opentelemetry/resources": "^2.0.1",
+    "@opentelemetry/sdk-node": "0.217.0",
+    "@opentelemetry/semantic-conventions": "^1.30.0",
+    "@repo/logger": "workspace:*"
+  }
+}