@hozon/store-telemetry 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Le Cam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,16 @@
-# Temporary Holding Version
+# @hozon/store-telemetry
 
-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.
+Persistent OpenTelemetry span store with trace lookup, upsert, and retention.
+
+```sh
+pnpm add @hozon/store-telemetry @hozon/db
+```
+
+```ts
+import { getTelemetryStore, telemetryStoreDefinition } from '@hozon/store-telemetry'
+
+db.register(telemetryStoreDefinition)
+const telemetry = await getTelemetryStore(db)
+```
+
+See the [store reference](../../docs/reference/stores/telemetry.md).

package/lib/api.d.ts

@@ -0,0 +1,5 @@
+import type { Adapter } from '@hozon/adapter';
+import type { Kysely } from 'kysely';
+import type { TelemetryTables } from './tables.js';
+import type { TelemetryStore } from './types.js';
+export declare function createTelemetryStoreAPI(db: Kysely<TelemetryTables>, adapter: Adapter): TelemetryStore;

package/lib/api.js

@@ -0,0 +1,72 @@
+import { chunk, withKeepSet, withStoreTransaction } from '@hozon/db';
+export function createTelemetryStoreAPI(db, adapter) {
+    return {
+        async addSpans (spans) {
+            if (spans.length === 0) return;
+            const rows = spans.map((span)=>({
+                    trace_id: span.traceID,
+                    span_id: span.spanID,
+                    start_time: span.startTime,
+                    end_time: span.endTime,
+                    data: adapter.encodeJSON(span)
+                }));
+            await withStoreTransaction(db, async (trx)=>{
+                let batch = [];
+                let pairs = new Set();
+                const insertBatch = async ()=>{
+                    if (batch.length === 0) return;
+                    await trx.insertInto('spans').values(batch).onConflict((conflict)=>conflict.columns([
+                            'trace_id',
+                            'span_id'
+                        ]).doUpdateSet((eb)=>({
+                                start_time: eb.ref('excluded.start_time'),
+                                end_time: eb.ref('excluded.end_time'),
+                                data: eb.ref('excluded.data')
+                            }))).execute();
+                    batch = [];
+                    pairs = new Set();
+                };
+                for (const row of rows){
+                    const pair = JSON.stringify([
+                        row.trace_id,
+                        row.span_id
+                    ]);
+                    if (pairs.has(pair) || batch.length === 100) await insertBatch();
+                    batch.push(row);
+                    pairs.add(pair);
+                }
+                await insertBatch();
+            });
+        },
+        async getSpans (traceID) {
+            const rows = await db.selectFrom('spans').select('data').where('trace_id', '=', traceID).orderBy('start_time').orderBy('seq').execute();
+            return rows.map((row)=>row.data);
+        },
+        async deleteByTrace (traceIDs) {
+            if (traceIDs.length === 0) return 0;
+            return withStoreTransaction(db, async (trx)=>{
+                let count = 0;
+                for (const ids of chunk(traceIDs)){
+                    const result = await trx.deleteFrom('spans').where('trace_id', 'in', ids).executeTakeFirstOrThrow();
+                    count += Number(result.numDeletedRows);
+                }
+                return count;
+            });
+        },
+        async deleteBefore (time, params) {
+            return withStoreTransaction(db, async (trx)=>{
+                if (params?.keepTraceIDs === undefined || params.keepTraceIDs.length === 0) {
+                    const result = await trx.deleteFrom('spans').where('end_time', '<', time).executeTakeFirstOrThrow();
+                    return Number(result.numDeletedRows);
+                }
+                return withKeepSet(trx, {
+                    table: 'keep_telemetry',
+                    ids: params.keepTraceIDs
+                }, async (selectKeep)=>{
+                    const result = await trx.deleteFrom('spans').where('end_time', '<', time).where('trace_id', 'not in', selectKeep()).executeTakeFirstOrThrow();
+                    return Number(result.numDeletedRows);
+                });
+            });
+        }
+    };
+}

package/lib/definition.d.ts

@@ -0,0 +1,6 @@
+import type { StoreDefinition, StoreProvider } from '@hozon/db';
+import type { TelemetryTables } from './tables.js';
+import type { TelemetryStore } from './types.js';
+export declare const TELEMETRY_STORE = "telemetry";
+export declare const telemetryStoreDefinition: StoreDefinition<TelemetryTables, TelemetryStore>;
+export declare function getTelemetryStore(provider: StoreProvider): Promise<TelemetryStore>;

package/lib/definition.js

@@ -0,0 +1,11 @@
+import { createTelemetryStoreAPI } from './api.js';
+import { telemetryStoreMigrations } from './migrations.js';
+export const TELEMETRY_STORE = 'telemetry';
+export const telemetryStoreDefinition = {
+    name: TELEMETRY_STORE,
+    migrations: telemetryStoreMigrations,
+    createAPI: createTelemetryStoreAPI
+};
+export async function getTelemetryStore(provider) {
+    return provider.getStore(TELEMETRY_STORE);
+}

package/lib/index.d.ts

@@ -0,0 +1,3 @@
+export { getTelemetryStore, TELEMETRY_STORE, telemetryStoreDefinition } from './definition.js';
+export type { TelemetryTables } from './tables.js';
+export type { StoredSpan, TelemetryStore } from './types.js';

package/lib/index.js

@@ -0,0 +1 @@
+export { getTelemetryStore, TELEMETRY_STORE, telemetryStoreDefinition } from './definition.js';

package/lib/migrations.d.ts

@@ -0,0 +1,3 @@
+import type { MigrationContext } from '@hozon/db';
+import type { Migration } from 'kysely/migration';
+export declare function telemetryStoreMigrations(ctx: MigrationContext): Record<string, Migration>;

package/lib/migrations.js

@@ -0,0 +1,24 @@
+export function telemetryStoreMigrations(ctx) {
+    return {
+        '0-init': {
+            async up (db) {
+                await db.schema.createTable('spans').addColumn('seq', ctx.types.serial, (column)=>{
+                    const primary = column.primaryKey();
+                    return ctx.kind === 'sqlite' ? primary.autoIncrement() : primary;
+                }).addColumn('trace_id', ctx.types.text, (column)=>column.notNull()).addColumn('span_id', ctx.types.text, (column)=>column.notNull()).addColumn('start_time', ctx.types.double, (column)=>column.notNull()).addColumn('end_time', ctx.types.double, (column)=>column.notNull()).addColumn('data', ctx.types.json, (column)=>column.notNull()).addUniqueConstraint(`${ctx.tablePrefix}_spans_trace_span`, [
+                    'trace_id',
+                    'span_id'
+                ]).execute();
+                await db.schema.createIndex(`${ctx.tablePrefix}_spans_trace_start_seq`).on('spans').columns([
+                    'trace_id',
+                    'start_time',
+                    'seq'
+                ]).execute();
+                await db.schema.createIndex(`${ctx.tablePrefix}_spans_end_time`).on('spans').column('end_time').execute();
+            },
+            async down (db) {
+                await db.schema.dropTable('spans').execute();
+            }
+        }
+    };
+}

package/lib/tables.d.ts

@@ -0,0 +1,12 @@
+import type { ColumnType, Generated } from 'kysely';
+import type { StoredSpan } from './types.js';
+export type TelemetryTables = {
+    spans: {
+        seq: Generated<number>;
+        trace_id: string;
+        span_id: string;
+        start_time: number;
+        end_time: number;
+        data: ColumnType<StoredSpan, unknown, unknown>;
+    };
+};

package/lib/tables.js

@@ -0,0 +1 @@
+export { };

package/lib/types.d.ts

@@ -0,0 +1,33 @@
+import type { JSONValue } from '@sozai/json';
+export type StoredSpan = {
+    traceID: string;
+    spanID: string;
+    parentSpanID?: string;
+    name: string;
+    kind: number;
+    startTime: number;
+    endTime: number;
+    status: {
+        code: number;
+        message?: string;
+    };
+    attributes: Record<string, JSONValue>;
+    events: Array<{
+        name: string;
+        time: number;
+        attributes: Record<string, JSONValue>;
+    }>;
+    links: Array<{
+        traceID: string;
+        spanID: string;
+    }>;
+};
+export type TelemetryStore = {
+    addSpans(spans: Array<StoredSpan>): Promise<void>;
+    getSpans(traceID: string): Promise<Array<StoredSpan>>;
+    deleteByTrace(traceIDs: Array<string>): Promise<number>;
+    /** An empty or omitted keepTraceIDs keeps nothing. */
+    deleteBefore(time: number, params?: {
+        keepTraceIDs?: Array<string>;
+    }): Promise<number>;
+};

package/lib/types.js

@@ -0,0 +1 @@
+export { };

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@hozon/store-telemetry",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Portable span store for Hozon",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TairuFramework/hozon.git",
+    "directory": "packages/store-telemetry"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "files": [
+    "lib/*"
+  ],
+  "dependencies": {
+    "@hozon/adapter": "^0.1.0",
+    "@hozon/db": "^0.2.0",
+    "@sozai/json": "^0.3.0",
+    "kysely": "^0.29.6"
+  },
+  "devDependencies": {
+    "@hozon/node-sqlite": "^0.1.0",
+    "@types/node": "^26.6.4",
+    "del-cli": "^7.0.0",
+    "vitest": "5.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
+    "build:clean": "del-cli lib",
+    "build:js": "del-cli \"lib/**/*.js\" && swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
+    "build:types": "del-cli \"lib/**/*.d.ts\" \"lib/**/*.d.ts.map\" && tsc --emitDeclarationOnly --skipLibCheck",
+    "build:types:ci": "tsc --emitDeclarationOnly --skipLibCheck --declarationMap false",
+    "test": "pnpm run test:types && pnpm run test:unit",
+    "test:types": "tsc --noEmit --skipLibCheck -p tsconfig.test.json",
+    "test:unit": "vitest run"
+  }
 }