@justanalyticsapp/node 0.1.0

package/dist/integrations/pino.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @file packages/node-sdk/src/integrations/pino.ts
+ * @description Pino transport for JustAnalytics log integration.
+ *
+ * Implements Story 046 - SDK Log Integration
+ *
+ * Creates a writable stream that parses Pino's newline-delimited JSON
+ * output and pipes log entries through the JustAnalytics SDK logger.
+ *
+ * Usage (programmatic):
+ * ```typescript
+ * import pino from 'pino';
+ * import { createJustAnalyticsPinoTransport } from '@justanalyticsapp/node/pino';
+ *
+ * const logger = pino(
+ *   { level: 'info' },
+ *   createJustAnalyticsPinoTransport(),
+ * );
+ * ```
+ *
+ * Usage (Pino transport API):
+ * ```typescript
+ * import pino from 'pino';
+ *
+ * const logger = pino({
+ *   transport: {
+ *     target: '@justanalyticsapp/node/pino',
+ *   },
+ * });
+ * ```
+ *
+ * The transport requires `pino` as a peer dependency.
+ */
+import { Writable } from 'stream';
+import type { LogLevel } from '../logger';
+/** Configuration options for the Pino transport */
+export interface JustAnalyticsPinoTransportOptions {
+    /** Custom mapping from Pino numeric levels to JA levels */
+    levelMap?: Record<number, LogLevel>;
+}
+/**
+ * Create a writable stream that pipes Pino log entries to JustAnalytics.
+ *
+ * The stream parses newline-delimited JSON from Pino, maps numeric levels
+ * to JA levels, strips Pino internal fields, and forwards log entries
+ * through JA.logger for batched transport with automatic trace context.
+ *
+ * @param options - Optional configuration for level mapping
+ * @returns A Writable stream compatible with Pino's destination API
+ */
+export declare function createJustAnalyticsPinoTransport(options?: JustAnalyticsPinoTransportOptions): Writable;
+export default createJustAnalyticsPinoTransport;

package/dist/integrations/pino.js

@@ -0,0 +1,153 @@
+"use strict";
+/**
+ * @file packages/node-sdk/src/integrations/pino.ts
+ * @description Pino transport for JustAnalytics log integration.
+ *
+ * Implements Story 046 - SDK Log Integration
+ *
+ * Creates a writable stream that parses Pino's newline-delimited JSON
+ * output and pipes log entries through the JustAnalytics SDK logger.
+ *
+ * Usage (programmatic):
+ * ```typescript
+ * import pino from 'pino';
+ * import { createJustAnalyticsPinoTransport } from '@justanalyticsapp/node/pino';
+ *
+ * const logger = pino(
+ *   { level: 'info' },
+ *   createJustAnalyticsPinoTransport(),
+ * );
+ * ```
+ *
+ * Usage (Pino transport API):
+ * ```typescript
+ * import pino from 'pino';
+ *
+ * const logger = pino({
+ *   transport: {
+ *     target: '@justanalyticsapp/node/pino',
+ *   },
+ * });
+ * ```
+ *
+ * The transport requires `pino` as a peer dependency.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createJustAnalyticsPinoTransport = createJustAnalyticsPinoTransport;
+const stream_1 = require("stream");
+/** Pino numeric level to JustAnalytics level mapping */
+const DEFAULT_PINO_LEVEL_MAP = {
+    10: 'debug', // pino 'trace'
+    20: 'debug', // pino 'debug'
+    30: 'info', // pino 'info'
+    40: 'warn', // pino 'warn'
+    50: 'error', // pino 'error'
+    60: 'fatal', // pino 'fatal'
+};
+/** Pino internal fields to exclude from attributes */
+const PINO_INTERNAL_FIELDS = new Set(['level', 'msg', 'time', 'pid', 'hostname', 'v']);
+/**
+ * Map a Pino numeric level to a JA LogLevel.
+ * Uses the exact level if found, otherwise finds the closest lower level.
+ * Defaults to 'info' if no match is found.
+ *
+ * @param pinoLevel - Pino numeric log level
+ * @param levelMap - Level mapping to use
+ * @returns The corresponding JA LogLevel
+ */
+function mapPinoLevel(pinoLevel, levelMap) {
+    if (levelMap[pinoLevel])
+        return levelMap[pinoLevel];
+    // Find closest lower level
+    const levels = Object.keys(levelMap)
+        .map(Number)
+        .sort((a, b) => b - a);
+    for (const l of levels) {
+        if (l <= pinoLevel)
+            return levelMap[l];
+    }
+    return 'info';
+}
+/**
+ * Create a writable stream that pipes Pino log entries to JustAnalytics.
+ *
+ * The stream parses newline-delimited JSON from Pino, maps numeric levels
+ * to JA levels, strips Pino internal fields, and forwards log entries
+ * through JA.logger for batched transport with automatic trace context.
+ *
+ * @param options - Optional configuration for level mapping
+ * @returns A Writable stream compatible with Pino's destination API
+ */
+function createJustAnalyticsPinoTransport(options) {
+    const levelMap = options?.levelMap
+        ? { ...DEFAULT_PINO_LEVEL_MAP, ...options.levelMap }
+        : { ...DEFAULT_PINO_LEVEL_MAP };
+    let buffer = '';
+    return new stream_1.Writable({
+        write(chunk, _encoding, callback) {
+            try {
+                buffer += chunk.toString();
+                const lines = buffer.split('\n');
+                // Keep the last partial line in the buffer
+                buffer = lines.pop() || '';
+                for (const line of lines) {
+                    if (!line.trim())
+                        continue;
+                    try {
+                        const obj = JSON.parse(line);
+                        const pinoLevel = typeof obj.level === 'number' ? obj.level : 30;
+                        const mappedLevel = mapPinoLevel(pinoLevel, levelMap);
+                        const message = obj.msg || '';
+                        // Extract attributes (everything except Pino internal fields)
+                        const attributes = {};
+                        for (const key of Object.keys(obj)) {
+                            if (!PINO_INTERNAL_FIELDS.has(key)) {
+                                attributes[key] = obj[key];
+                            }
+                        }
+                        // Lazy import to avoid circular dependency
+                        const JA = require('../index').default;
+                        if (JA && JA.logger) {
+                            JA.logger.log(mappedLevel, message, attributes);
+                        }
+                    }
+                    catch {
+                        // Skip malformed JSON lines
+                    }
+                }
+            }
+            catch {
+                // Never throw from transport
+            }
+            callback();
+        },
+        final(callback) {
+            // Process any remaining data in the buffer
+            if (buffer.trim()) {
+                try {
+                    const obj = JSON.parse(buffer);
+                    const pinoLevel = typeof obj.level === 'number' ? obj.level : 30;
+                    const mappedLevel = mapPinoLevel(pinoLevel, levelMap);
+                    const message = obj.msg || '';
+                    const attributes = {};
+                    for (const key of Object.keys(obj)) {
+                        if (!PINO_INTERNAL_FIELDS.has(key)) {
+                            attributes[key] = obj[key];
+                        }
+                    }
+                    const JA = require('../index').default;
+                    if (JA && JA.logger) {
+                        JA.logger.log(mappedLevel, message, attributes);
+                    }
+                }
+                catch {
+                    // Skip malformed data
+                }
+            }
+            callback();
+        },
+    });
+}
+// Default export for Pino transport API: pino({ transport: { target: '...' } })
+exports.default = createJustAnalyticsPinoTransport;
+//# sourceMappingURL=pino.js.map

package/dist/integrations/pino.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pino.js","sourceRoot":"","sources":["../../src/integrations/pino.ts"],"names":[],"mappings":"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"}

package/dist/integrations/redis.d.ts

@@ -0,0 +1,190 @@
+/**
+ * @file packages/node-sdk/src/integrations/redis.ts
+ * @description Redis auto-instrumentation integration for the JustAnalytics Node.js SDK.
+ *
+ * Implements Story 040 - Redis Auto-Instrumentation
+ *
+ * Monkey-patches `ioredis` (Redis.prototype.sendCommand) and/or `@redis/client`
+ * (Commander.prototype.sendCommand) to automatically create `redis.command` spans
+ * for all Redis operations. This captures all Redis traffic regardless of which
+ * higher-level abstraction the developer uses.
+ *
+ * Follows the same monkey-patching pattern established in Story 036 (HTTP Auto-Instrumentation)
+ * and Story 039 (PostgreSQL Auto-Instrumentation):
+ * - Integration class with `enable()`/`disable()` lifecycle methods
+ * - Original function preservation for clean teardown
+ * - Integration with AsyncLocalStorage context for automatic parent-child span relationships
+ * - Fail-open design: if instrumentation code fails, the original command executes normally
+ *
+ * CRITICAL SECURITY: Redis values are NEVER captured in span attributes.
+ * Only command name + key name(s) are recorded in `db.statement`.
+ *
+ * References:
+ * - OpenTelemetry Database Semantic Conventions (db.system, db.statement, etc.)
+ * - Story 035 - Node.js SDK Core (Span, context, transport)
+ * - Story 036 - HTTP Auto-Instrumentation (integration pattern)
+ * - Story 039 - PostgreSQL Auto-Instrumentation (database integration pattern)
+ */
+import { Span } from '../span';
+/**
+ * Configuration for the Redis auto-instrumentation integration.
+ */
+export interface RedisIntegrationOptions {
+    /** Enable/disable the integration (default: true) */
+    enabled?: boolean;
+    /**
+     * Maximum character length for the db.statement attribute.
+     * Statements longer than this are truncated with '...' suffix.
+     * (default: 512)
+     */
+    maxStatementLength?: number;
+}
+/**
+ * Format the db.statement attribute from a Redis command and its arguments.
+ *
+ * Rules:
+ * 1. Command name is always UPPERCASE
+ * 2. For NO_KEY_COMMANDS, statement is just the command name
+ * 3. For known commands, include only key name(s) per KEY_ONLY_COMMANDS mapping
+ * 4. For unknown commands, include only the first argument (assumed to be the key)
+ * 5. Values are NEVER included
+ * 6. Truncate to maxStatementLength
+ *
+ * @param command - Redis command name (e.g., "get", "SET", "hget")
+ * @param args - Command arguments array
+ * @param maxLength - Maximum statement length (default: 512)
+ * @returns Formatted statement (e.g., "GET user:123", "HGET cache:data field")
+ */
+export declare function formatRedisStatement(command: string, args: unknown[], maxLength?: number): string;
+/**
+ * Sanitize a Redis connection string by masking the password.
+ *
+ * Also handles raw redis:// URLs by replacing the password portion.
+ *
+ * @param connStr - Raw connection string potentially containing a password
+ * @returns Sanitized connection string with password masked
+ */
+export declare function sanitizeRedisConnectionString(connStr: string): string;
+/**
+ * Build a sanitized Redis connection string from individual components.
+ *
+ * @param host - Redis host
+ * @param port - Redis port
+ * @param password - Redis password (will be masked)
+ * @param db - Redis database index
+ * @param user - Redis user (for ACL auth)
+ * @returns Sanitized connection string (e.g., "redis://user:***@host:6379/0")
+ */
+export declare function sanitizeRedisConnectionString(host: string, port: number, password?: string, db?: number, user?: string): string;
+/**
+ * RedisIntegration monkey-patches ioredis and/or @redis/client
+ * to auto-create redis.command spans for all Redis operations.
+ *
+ * Follows the same pattern as HttpIntegration (Story 036) and
+ * PgIntegration (Story 039):
+ * - Constructor accepts serviceName, options, onSpanEnd callback
+ * - enable() patches, disable() restores
+ * - Original functions preserved for clean teardown
+ * - Fail-open design: instrumentation failures never crash the host process
+ *
+ * Security: NEVER captures Redis values in span attributes.
+ * Only command name + key name(s) are recorded.
+ */
+export declare class RedisIntegration {
+    private _enabled;
+    private _options;
+    private _serviceName;
+    private _onSpanEnd;
+    private _originalIoRedisSendCommand;
+    private _ioRedisPrototype;
+    private _originalNodeRedisSendCommand;
+    private _nodeRedisPrototype;
+    /**
+     * Create a new RedisIntegration.
+     *
+     * @param serviceName - The service name for span attribution
+     * @param options - Integration configuration options
+     * @param onSpanEnd - Callback invoked when a span ends (enqueues to transport)
+     */
+    constructor(serviceName: string, options: RedisIntegrationOptions | undefined, onSpanEnd: (span: Span) => void);
+    /**
+     * Activate the integration: load Redis modules and patch prototypes.
+     *
+     * Attempts to load both ioredis and @redis/client independently.
+     * If neither is installed, silently skips. If only one is installed,
+     * only that library is patched.
+     *
+     * Calling enable() when already enabled is a no-op (idempotent).
+     */
+    enable(): void;
+    /**
+     * Deactivate: restore original Redis functions.
+     *
+     * Calling disable() when not enabled is a no-op (idempotent).
+     */
+    disable(): void;
+    /**
+     * Attempt to load and patch ioredis.
+     *
+     * ioredis routes ALL commands (including pipeline/cluster) through
+     * Redis.prototype.sendCommand. By patching this one method, we capture
+     * all commands regardless of which method the developer calls.
+     */
+    private _patchIoRedis;
+    /**
+     * Attempt to load and patch @redis/client.
+     *
+     * node-redis v4+ uses a Commander class. All commands go through
+     * sendCommand(args: string[]) where args[0] is the command name.
+     */
+    private _patchNodeRedis;
+    /**
+     * Restore all patched functions to their originals.
+     */
+    private _restoreOriginals;
+    /**
+     * Wrap ioredis Redis.prototype.sendCommand to create redis.command spans.
+     *
+     * ioredis routes ALL commands (including pipeline/cluster) through
+     * sendCommand(command: Command). The Command object has:
+     * - command.name: string (e.g., "get", "set", "hget")
+     * - command.args: unknown[] (command arguments)
+     * - command.promise: Promise (resolves/rejects when the command completes)
+     *
+     * @param original - The original sendCommand function
+     * @returns A wrapped version
+     */
+    private _wrapIoRedisSendCommand;
+    /**
+     * Wrap @redis/client's sendCommand to create redis.command spans.
+     *
+     * node-redis v4+ uses a Commander class that dispatches all commands
+     * through a sendCommand method. The method signature is:
+     * sendCommand(args: string[], options?: CommandOptions): Promise<unknown>
+     *
+     * Where args[0] is the command name and args[1..] are command arguments.
+     *
+     * @param original - The original sendCommand function
+     * @returns A wrapped version
+     */
+    private _wrapNodeRedisSendCommand;
+    /**
+     * Extract connection info from an ioredis client instance.
+     *
+     * ioredis stores connection options on the instance as `this.options`.
+     *
+     * @param client - The ioredis client instance (`this` in the patched method)
+     * @returns Attributes object with connection info
+     */
+    private _getIoRedisConnectionInfo;
+    /**
+     * Extract connection info from a @redis/client instance.
+     *
+     * node-redis v4+ stores connection options in various ways depending
+     * on the version. We try multiple paths defensively.
+     *
+     * @param client - The @redis/client instance (`this` in the patched method)
+     * @returns Attributes object with connection info
+     */
+    private _getNodeRedisConnectionInfo;
+}