@tansy/logs-otlp 0.0.0-stage → 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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Mohamed Salah
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,13 @@
1
- # Temporary Holding Version
1
+ <!-- Generated by scripts/package-metadata.mjs. Change that script, not this file. -->
2
2
 
3
- 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.
3
+ # @tansy/logs-otlp
4
+
5
+ Sends the audit log and request log over OpenTelemetry (OTLP/HTTP), to Grafana, Honeycomb, Datadog, Axiom or any collector.
6
+
7
+ ```bash
8
+ npm install @tansy/logs-otlp
9
+ ```
10
+
11
+ Add it to `tansy.config.ts`. See [the logs-otlp plugin documentation](https://github.com/mhmdsalahsebai/tansy/blob/main/docs/plugins/logs-otlp.md) for what it adds and the options it takes.
12
+
13
+ A first-party plugin for [tansy](https://github.com/mhmdsalahsebai/tansy), a self-hosted, runtime-schema CMS for Next.js. MIT licensed.
package/index.d.ts ADDED
@@ -0,0 +1,26 @@
1
+ import { type OtlpOptions, type RequestRecordInput } from "./otlp";
2
+ export { auditRecord, exportRequest, logsUrl, parseHeaders, requestRecord } from "./otlp";
3
+ export type { OtlpOptions } from "./otlp";
4
+ /**
5
+ * Sends the audit log over OpenTelemetry (OTLP/HTTP with JSON), which Grafana Cloud, Honeycomb,
6
+ * New Relic, SigNoz, Datadog, Axiom and any OpenTelemetry Collector take. The database keeps its
7
+ * copy as before; this is a copy outside it. Entries are batched every few seconds and retried
8
+ * with backoff while the backend is down, held in memory up to a limit, so a restart during an
9
+ * outage loses what was waiting: the database still has them. See docs/plugins/logs-otlp.md.
10
+ *
11
+ * For the request log, put `otlpDestination()` in the request-logs plugin's destinations.
12
+ */
13
+ export declare function logsOtlp(options?: OtlpOptions, fetcher?: typeof fetch): import("tansy/plugin").CmsPlugin;
14
+ /**
15
+ * The request log over OTLP, as a destination for the request-logs plugin:
16
+ * `requestLogs({ destinations: [otlpDestination()] })`. It takes the same options and variables
17
+ * as `logsOtlp`. The request-logs plugin batches and retries.
18
+ */
19
+ export declare function otlpDestination(options?: OtlpOptions & {
20
+ name?: string;
21
+ label?: string;
22
+ }, fetcher?: typeof fetch): {
23
+ name: string;
24
+ label: string;
25
+ write: (entries: RequestRecordInput[]) => Promise<void>;
26
+ };
package/index.js ADDED
@@ -0,0 +1,93 @@
1
+ import { randomUUID } from "node:crypto";
2
+ import { definePlugin } from "tansy/plugin";
3
+ import { auditRecord, createSender, requestRecord, resolveOptions } from "./otlp";
4
+ export { auditRecord, exportRequest, logsUrl, parseHeaders, requestRecord } from "./otlp";
5
+ const NAME = "logs-otlp";
6
+ const FLUSH_MS = 2000;
7
+ const BATCH = 500;
8
+ /** Entries held while the backend is down. Past it, the oldest are dropped and counted. */
9
+ const MAX_WAITING = 10_000;
10
+ /** Seconds before each retry, the last repeated. */
11
+ const RETRY_DELAYS = [5, 30, 120, 600];
12
+ /**
13
+ * Sends the audit log over OpenTelemetry (OTLP/HTTP with JSON), which Grafana Cloud, Honeycomb,
14
+ * New Relic, SigNoz, Datadog, Axiom and any OpenTelemetry Collector take. The database keeps its
15
+ * copy as before; this is a copy outside it. Entries are batched every few seconds and retried
16
+ * with backoff while the backend is down, held in memory up to a limit, so a restart during an
17
+ * outage loses what was waiting: the database still has them. See docs/plugins/logs-otlp.md.
18
+ *
19
+ * For the request log, put `otlpDestination()` in the request-logs plugin's destinations.
20
+ */
21
+ export function logsOtlp(options = {}, fetcher = fetch) {
22
+ const send = createSender(resolveOptions(options), fetcher);
23
+ const state = (globalThis.cmsLogsOtlp ??= { waiting: [], dropped: 0, failures: 0, timer: null, sending: null });
24
+ function schedule(ms) {
25
+ if (state.timer)
26
+ return;
27
+ state.timer = setTimeout(() => {
28
+ state.timer = null;
29
+ void flush();
30
+ }, ms);
31
+ state.timer.unref?.();
32
+ }
33
+ /** Sends what's waiting, a batch at a time. A failure keeps the batch and waits longer before the next try. */
34
+ function flush() {
35
+ state.sending ??= (async () => {
36
+ try {
37
+ while (state.waiting.length) {
38
+ const batch = state.waiting.slice(0, BATCH);
39
+ try {
40
+ await send(batch.map(auditRecord));
41
+ }
42
+ catch (error) {
43
+ state.failures += 1;
44
+ const delay = RETRY_DELAYS[Math.min(state.failures - 1, RETRY_DELAYS.length - 1)];
45
+ if (state.failures >= 3)
46
+ console.error(`[${NAME}] couldn't send the audit log ${state.failures} times in a row:`, error instanceof Error ? error.message : error);
47
+ schedule(delay * 1000);
48
+ return;
49
+ }
50
+ state.waiting.splice(0, batch.length);
51
+ state.failures = 0;
52
+ }
53
+ if (state.dropped) {
54
+ console.warn(`[${NAME}] dropped ${state.dropped} audit entries because too many were waiting`);
55
+ state.dropped = 0;
56
+ }
57
+ }
58
+ finally {
59
+ state.sending = null;
60
+ }
61
+ })();
62
+ return state.sending;
63
+ }
64
+ function onAudit(event) {
65
+ state.waiting.push({ ...event, id: randomUUID(), at: new Date().toISOString() });
66
+ if (state.waiting.length > MAX_WAITING)
67
+ state.dropped += state.waiting.splice(0, state.waiting.length - MAX_WAITING).length;
68
+ // While retrying, the backoff timer is already set and this waits for it.
69
+ if (state.failures === 0)
70
+ schedule(FLUSH_MS);
71
+ }
72
+ return definePlugin({
73
+ name: NAME,
74
+ version: "0.1.0",
75
+ apiVersion: 1,
76
+ requires: { cms: "^0.1.0" },
77
+ auth: { onAudit },
78
+ });
79
+ }
80
+ /**
81
+ * The request log over OTLP, as a destination for the request-logs plugin:
82
+ * `requestLogs({ destinations: [otlpDestination()] })`. It takes the same options and variables
83
+ * as `logsOtlp`. The request-logs plugin batches and retries.
84
+ */
85
+ export function otlpDestination(options = {}, fetcher = fetch) {
86
+ const resolved = resolveOptions(options);
87
+ const send = createSender(resolved, fetcher);
88
+ return {
89
+ name: options.name ?? "otlp",
90
+ label: options.label ?? `OpenTelemetry (${new URL(resolved.url).host})`,
91
+ write: (entries) => send(entries.map(requestRecord)),
92
+ };
93
+ }
package/otlp.d.ts ADDED
@@ -0,0 +1,114 @@
1
+ /** OTLP/HTTP with JSON: the address, the headers, and log records for both logs. No server imports, so it's easy to test. */
2
+ /** One audit entry as this plugin sends it: the event as core recorded it, stamped on arrival. */
3
+ export interface AuditRecordInput {
4
+ /** Unique, and the same on every attempt, so a backend can drop a repeat. */
5
+ id: string;
6
+ /** ISO 8601, in UTC. */
7
+ at: string;
8
+ action: string;
9
+ outcome: "success" | "failure" | "denied";
10
+ actorId?: string | null;
11
+ actorEmail?: string | null;
12
+ actorKind?: string;
13
+ targetType?: string;
14
+ targetId?: string;
15
+ ipAddress?: string | null;
16
+ userAgent?: string | null;
17
+ scope?: string | null;
18
+ /** Already sanitized by core. */
19
+ metadata?: Record<string, unknown>;
20
+ }
21
+ /** One request log entry, as the request-logs plugin hands it to a destination. */
22
+ export interface RequestRecordInput {
23
+ at: string;
24
+ method: string;
25
+ path: string;
26
+ status: number;
27
+ durationMs: number;
28
+ actorId: string | null;
29
+ ipAddress: string | null;
30
+ userAgent: string | null;
31
+ }
32
+ export interface OtlpOptions {
33
+ /**
34
+ * The OTLP/HTTP base address, such as http://collector:4318 or
35
+ * https://otlp-gateway-prod-eu-west-2.grafana.net/otlp. Logs go to its /v1/logs. Defaults to
36
+ * OTEL_EXPORTER_OTLP_LOGS_ENDPOINT (the full address) or OTEL_EXPORTER_OTLP_ENDPOINT.
37
+ */
38
+ endpoint?: string;
39
+ /** Sent with each request, for the backend's key. Defaults to OTEL_EXPORTER_OTLP_HEADERS, as `name=value,name=value`. */
40
+ headers?: Record<string, string>;
41
+ /** The `service.name` the logs are under. Defaults to OTEL_SERVICE_NAME, then "tansy". */
42
+ serviceName?: string;
43
+ /** Milliseconds per request. 10 seconds when left out. */
44
+ timeoutMs?: number;
45
+ }
46
+ /** `name=value,name=value`, with values percent-encoded, as OpenTelemetry's variables have them. */
47
+ export declare function parseHeaders(value: string | undefined): Record<string, string>;
48
+ /**
49
+ * The logs address: a base address gets /v1/logs, a full logs address is used as it is. Only
50
+ * http and https, and no user, password or query in it: keys go in headers.
51
+ */
52
+ export declare function logsUrl({ base, full }: {
53
+ base?: string;
54
+ full?: string;
55
+ }): string;
56
+ /** Where to send and how, from the options and then OpenTelemetry's own variables, in the order OpenTelemetry reads them. */
57
+ export declare function resolveOptions(options: OtlpOptions, env?: Record<string, string | undefined>): {
58
+ url: string;
59
+ headers: {
60
+ "content-type": string;
61
+ };
62
+ serviceName: string;
63
+ timeoutMs: number;
64
+ };
65
+ type Value = {
66
+ stringValue: string;
67
+ } | {
68
+ intValue: string;
69
+ } | {
70
+ boolValue: boolean;
71
+ };
72
+ interface Attribute {
73
+ key: string;
74
+ value: Value;
75
+ }
76
+ export declare function auditRecord(entry: AuditRecordInput): {
77
+ eventName: string;
78
+ body: {
79
+ stringValue: string;
80
+ };
81
+ attributes: Attribute[];
82
+ severityNumber: number;
83
+ severityText: "ERROR" | "INFO" | "WARN";
84
+ timeUnixNano: string;
85
+ };
86
+ export declare function requestRecord(entry: RequestRecordInput): {
87
+ body: {
88
+ stringValue: string;
89
+ };
90
+ attributes: Attribute[];
91
+ severityNumber: number;
92
+ severityText: "ERROR" | "INFO" | "WARN";
93
+ timeUnixNano: string;
94
+ };
95
+ /** One OTLP/HTTP JSON export request. */
96
+ export declare const exportRequest: (serviceName: string, logRecords: object[]) => {
97
+ resourceLogs: {
98
+ resource: {
99
+ attributes: Attribute[];
100
+ };
101
+ scopeLogs: {
102
+ scope: {
103
+ name: string;
104
+ };
105
+ logRecords: object[];
106
+ }[];
107
+ }[];
108
+ };
109
+ /**
110
+ * Sends records in one request. Only the status of a refusal is reported, never what the
111
+ * backend said back, which can quote the key.
112
+ */
113
+ export declare function createSender(resolved: ReturnType<typeof resolveOptions>, fetcher?: typeof fetch): (records: object[]) => Promise<void>;
114
+ export {};
package/otlp.js ADDED
@@ -0,0 +1,140 @@
1
+ /** OTLP/HTTP with JSON: the address, the headers, and log records for both logs. No server imports, so it's easy to test. */
2
+ /** `name=value,name=value`, with values percent-encoded, as OpenTelemetry's variables have them. */
3
+ export function parseHeaders(value) {
4
+ const headers = {};
5
+ for (const pair of (value ?? "").split(",")) {
6
+ const at = pair.indexOf("=");
7
+ if (at <= 0)
8
+ continue;
9
+ const name = pair.slice(0, at).trim();
10
+ let text = pair.slice(at + 1).trim();
11
+ try {
12
+ text = decodeURIComponent(text);
13
+ }
14
+ catch {
15
+ // Left as written.
16
+ }
17
+ if (name)
18
+ headers[name] = text;
19
+ }
20
+ return headers;
21
+ }
22
+ /**
23
+ * The logs address: a base address gets /v1/logs, a full logs address is used as it is. Only
24
+ * http and https, and no user, password or query in it: keys go in headers.
25
+ */
26
+ export function logsUrl({ base, full }) {
27
+ const given = base ?? full;
28
+ let url;
29
+ try {
30
+ url = new URL(given ?? "");
31
+ }
32
+ catch {
33
+ throw new Error("OTLP logs need an endpoint, such as http://collector:4318. Set it or OTEL_EXPORTER_OTLP_ENDPOINT.");
34
+ }
35
+ if (url.protocol !== "https:" && url.protocol !== "http:")
36
+ throw new Error("The OTLP endpoint must start with https:// or http://.");
37
+ if (url.username || url.password || url.search || url.hash)
38
+ throw new Error("The OTLP endpoint can't hold a user, password, query or fragment. Pass keys as headers.");
39
+ const address = url.href.replace(/\/+$/, "");
40
+ return base === undefined ? address : `${address}/v1/logs`;
41
+ }
42
+ /** Where to send and how, from the options and then OpenTelemetry's own variables, in the order OpenTelemetry reads them. */
43
+ export function resolveOptions(options, env = process.env) {
44
+ const url = options.endpoint !== undefined || !env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
45
+ ? logsUrl({ base: options.endpoint ?? env.OTEL_EXPORTER_OTLP_ENDPOINT })
46
+ : logsUrl({ full: env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT });
47
+ return {
48
+ url,
49
+ headers: { "content-type": "application/json", ...(options.headers ?? parseHeaders(env.OTEL_EXPORTER_OTLP_HEADERS)) },
50
+ serviceName: options.serviceName ?? env.OTEL_SERVICE_NAME ?? "tansy",
51
+ timeoutMs: options.timeoutMs ?? 10_000,
52
+ };
53
+ }
54
+ const attribute = (key, value) => {
55
+ if (value === null || value === undefined || value === "")
56
+ return [];
57
+ if (typeof value === "boolean")
58
+ return [{ key, value: { boolValue: value } }];
59
+ if (typeof value === "number" && Number.isInteger(value))
60
+ return [{ key, value: { intValue: String(value) } }];
61
+ return [{ key, value: { stringValue: typeof value === "string" ? value : JSON.stringify(value) } }];
62
+ };
63
+ /** Milliseconds with six zeros, as a string: past 2^53, so never through a number. */
64
+ const nanos = (iso) => `${Date.parse(iso)}000000`;
65
+ /** OpenTelemetry's severity numbers: INFO 9, WARN 13, ERROR 17. */
66
+ const severity = (level) => ({ severityNumber: { INFO: 9, WARN: 13, ERROR: 17 }[level], severityText: level });
67
+ export function auditRecord(entry) {
68
+ return {
69
+ timeUnixNano: nanos(entry.at),
70
+ ...severity(entry.outcome === "success" ? "INFO" : "WARN"),
71
+ eventName: entry.action,
72
+ body: { stringValue: entry.action },
73
+ attributes: [
74
+ ...attribute("log.name", "audit"),
75
+ ...attribute("event.name", entry.action),
76
+ ...attribute("tansy.audit.id", entry.id),
77
+ ...attribute("tansy.audit.outcome", entry.outcome),
78
+ ...attribute("tansy.scope", entry.scope),
79
+ ...attribute("enduser.id", entry.actorId),
80
+ ...attribute("tansy.actor.email", entry.actorEmail),
81
+ ...attribute("tansy.actor.kind", entry.actorKind),
82
+ ...attribute("tansy.target.type", entry.targetType),
83
+ ...attribute("tansy.target.id", entry.targetId),
84
+ ...attribute("client.address", entry.ipAddress),
85
+ ...attribute("user_agent.original", entry.userAgent),
86
+ ...attribute("tansy.audit.metadata", entry.metadata && Object.keys(entry.metadata).length ? entry.metadata : null),
87
+ ],
88
+ };
89
+ }
90
+ export function requestRecord(entry) {
91
+ return {
92
+ timeUnixNano: nanos(entry.at),
93
+ ...severity(entry.status >= 500 ? "ERROR" : entry.status >= 400 ? "WARN" : "INFO"),
94
+ body: { stringValue: `${entry.method} ${entry.path} ${entry.status}` },
95
+ attributes: [
96
+ ...attribute("log.name", "request"),
97
+ ...attribute("http.request.method", entry.method),
98
+ ...attribute("url.path", entry.path),
99
+ ...attribute("http.response.status_code", entry.status),
100
+ ...attribute("tansy.duration_ms", entry.durationMs),
101
+ ...attribute("enduser.id", entry.actorId),
102
+ ...attribute("client.address", entry.ipAddress),
103
+ ...attribute("user_agent.original", entry.userAgent),
104
+ ],
105
+ };
106
+ }
107
+ /** One OTLP/HTTP JSON export request. */
108
+ export const exportRequest = (serviceName, logRecords) => ({
109
+ resourceLogs: [{
110
+ resource: { attributes: attribute("service.name", serviceName) },
111
+ scopeLogs: [{ scope: { name: "tansy" }, logRecords }],
112
+ }],
113
+ });
114
+ /**
115
+ * Sends records in one request. Only the status of a refusal is reported, never what the
116
+ * backend said back, which can quote the key.
117
+ */
118
+ export function createSender(resolved, fetcher = fetch) {
119
+ return async function send(records) {
120
+ if (!records.length)
121
+ return;
122
+ let response;
123
+ try {
124
+ response = await fetcher(resolved.url, {
125
+ method: "POST",
126
+ headers: resolved.headers,
127
+ body: JSON.stringify(exportRequest(resolved.serviceName, records)),
128
+ redirect: "error",
129
+ cache: "no-store",
130
+ signal: AbortSignal.timeout(resolved.timeoutMs),
131
+ });
132
+ }
133
+ catch {
134
+ throw new Error("The OTLP endpoint couldn't be reached.");
135
+ }
136
+ await response.body?.cancel().catch(() => { });
137
+ if (!response.ok)
138
+ throw new Error(`The OTLP endpoint answered ${response.status}.`);
139
+ };
140
+ }
package/package.json CHANGED
@@ -1,6 +1,29 @@
1
1
  {
2
2
  "name": "@tansy/logs-otlp",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Sends the audit log and request log over OpenTelemetry (OTLP/HTTP), to Grafana, Honeycomb, Datadog, Axiom or any collector.",
5
+ "keywords": [
6
+ "tansy",
7
+ "tansy-plugin",
8
+ "cms",
9
+ "nextjs"
10
+ ],
11
+ "license": "MIT",
12
+ "author": "Mohamed Salah <mohamedsalahsebai@gmail.com>",
13
+ "homepage": "https://github.com/mhmdsalahsebai/tansy",
14
+ "repository": {
15
+ "type": "git",
16
+ "url": "git+https://github.com/mhmdsalahsebai/tansy.git",
17
+ "directory": "plugins/logs-otlp"
18
+ },
19
+ "bugs": "https://github.com/mhmdsalahsebai/tansy/issues",
20
+ "exports": {
21
+ ".": {
22
+ "types": "./index.d.ts",
23
+ "default": "./index.js"
24
+ }
25
+ },
26
+ "peerDependencies": {
27
+ "tansy": "^0.1.0"
28
+ }
29
+ }