graftcode-appinsights-connector 0.0.0-stage → 1.0.3

package/README.md

@@ -1,3 +1,57 @@
-# Temporary Holding Version
+# graftcode-appinsights-connector (Node.js)
 
-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.
+One-call Azure Application Insights setup for Node.js services that use Graftcode: traces, logs, and Graftcode call instrumentation.
+
+## Quick start
+
+Call once, as early as possible. For a web server, load before the HTTP framework (e.g. `node --import ./telemetry.js server.js`):
+
+```js
+import { useGraftCodeAppInsights } from 'graftcode-appinsights-connector'
+
+export const telemetry = useGraftCodeAppInsights({
+  serviceName: 'MyService',
+  graftcode: {
+    libraries: { 'ws://localhost:9180/ws': 'MyNodeLib' },
+  },
+})
+```
+
+## Options (`GraftCodeAppInsightsOptions`)
+
+| Option | Description |
+|--------|-------------|
+| `serviceName` | Cloud role name in Application Insights (required). |
+| `connectionString` | Defaults to `APPLICATIONINSIGHTS_CONNECTION_STRING`. |
+| `tracesPerSecond` | Rate-limit sampling; default keeps every trace (`0`). |
+| `samplingRatio` | Fixed ratio 0–1 when `tracesPerSecond` is not used; default `1`. |
+| `logLevel` | Lowest level for app and Graftcode logs: `debug`, `info`, `warning`, `error`. Default `info`. |
+| `console` | Also print app logs to stdout. Default `true`. |
+| `graftcode` | `GraftcodeInstrumentation` options, or `false` to omit Graftcode instrumentation. |
+| `instrumentations` | Additional OpenTelemetry instrumentations to register. |
+| `azureMonitor` | Advanced `@azure/monitor-opentelemetry` options (merged first). |
+
+## Return value (`GraftCodeTelemetry`)
+
+| Member | Description |
+|--------|-------------|
+| `serviceName` | Configured role name. |
+| `isExporting` | `true` when a connection string is configured. |
+| `tracer` | OpenTelemetry tracer for the service. |
+| `logger` | App logger (`debug`, `info`, `warn`, `error`) exported to OpenTelemetry logs. |
+| `flush()` | Sends buffered telemetry now. |
+| `shutdown()` | Flush and stop; safe to call more than once. |
+
+`useGraftCodeAppInsights` is single-process: a second call with the same `serviceName` returns the existing instance; a different name throws.
+
+## Without a connection string
+
+Telemetry is not exported to Azure, but a local `NodeTracerProvider` still assigns real trace IDs so context flows through Graftcode calls. A warning is logged once.
+
+## HTTP auto-instrumentation
+
+Azure Monitor HTTP instrumentation stays enabled. Outgoing requests that are WebSocket upgrades (`Upgrade: websocket`) are ignored so the long-lived handshake is not tied to a single HTTP request; each Graft call is already described by the Graftcode span.
+
+## App logger
+
+Application logs use OpenTelemetry Logs with severity mapping and optional console output (`label: serviceName: message`). Errors attach redacted exception attributes.

package/package.json

@@ -1,6 +1,42 @@
 {
-  "name": "graftcode-appinsights-connector",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "graftcode-appinsights-connector",
+    "version": "1.0.3",
+    "description": "One-call Azure Application Insights setup for Node.js services that use Graftcode: traces, logs and Graftcode call instrumentation.",
+    "license": "ISC",
+    "author": "Graftcode S.A.",
+    "type": "module",
+    "main": "./src/index.js",
+    "types": "./src/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./src/index.d.ts",
+            "default": "./src/index.js"
+        }
+    },
+    "files": [
+        "README.md",
+        "src"
+    ],
+    "engines": {
+        "node": ">=20"
+    },
+    "scripts": {
+        "test": "node --test \"test/**/*.test.js\""
+    },
+    "dependencies": {
+        "@azure/monitor-opentelemetry": "^1.20.1",
+        "@opentelemetry/api": "^1.9.1",
+        "@opentelemetry/api-logs": "^0.221.0",
+        "@opentelemetry/instrumentation": "^0.221.0",
+        "@opentelemetry/resources": "^2.10.0",
+        "@opentelemetry/sdk-trace-node": "^2.10.0"
+    },
+    "peerDependencies": {
+        "graftcode-instrumentation": "^1.0.0",
+        "hypertube-nodejs-sdk": "*"
+    },
+    "devDependencies": {
+        "graftcode-instrumentation": "file:../../../Instrumentation/nodejs",
+        "hypertube-nodejs-sdk": "file:../../../../../NewHT/HYPERTUBE/src/js/hypertube-nodejs-sdk"
+    }
+}

package/src/appLogger.js

@@ -0,0 +1,44 @@
+import { context } from '@opentelemetry/api'
+import { logs } from '@opentelemetry/api-logs'
+import { LogsLevel, LogsRedactor } from 'hypertube-nodejs-sdk/abstractions'
+
+const SEVERITIES = {
+    [LogsLevel.Debug]: [5, 'DEBUG', 'dbug'],
+    [LogsLevel.Info]: [9, 'INFO', 'info'],
+    [LogsLevel.Warning]: [13, 'WARN', 'warn'],
+    [LogsLevel.Error]: [17, 'ERROR', 'fail'],
+}
+
+export function createAppLogger(serviceName, minimumLevel, toConsole) {
+    const logger = logs.getLogger(serviceName)
+
+    const write = (level, message, details) => {
+        if (level < minimumLevel) {
+            return
+        }
+
+        const [severityNumber, severityText, label] = SEVERITIES[level]
+        const attributes = details instanceof Error ? exceptionAttributes(details) : { ...details }
+        logger.emit({ severityNumber, severityText, body: message, attributes, context: context.active() })
+
+        if (toConsole) {
+            const suffix = details instanceof Error ? ` ${details.name}: ${details.message}` : ''
+            process.stdout.write(`${label}: ${serviceName}: ${message}${suffix}\n`)
+        }
+    }
+
+    return {
+        debug: (message, attributes) => write(LogsLevel.Debug, message, attributes),
+        info: (message, attributes) => write(LogsLevel.Info, message, attributes),
+        warn: (message, attributes) => write(LogsLevel.Warning, message, attributes),
+        error: (message, errorOrAttributes) => write(LogsLevel.Error, message, errorOrAttributes),
+    }
+}
+
+function exceptionAttributes(error) {
+    return {
+        'exception.type': error.name,
+        'exception.message': String(LogsRedactor.redactValue(error.message) ?? ''),
+        'exception.stacktrace': error.stack ? LogsRedactor.redactBody(error.stack) : undefined,
+    }
+}

package/src/index.d.ts

@@ -0,0 +1,36 @@
+import type { AzureMonitorOpenTelemetryOptions } from '@azure/monitor-opentelemetry'
+import type { Tracer } from '@opentelemetry/api'
+import type { Instrumentation } from '@opentelemetry/instrumentation'
+import type { GraftcodeInstrumentationConfig } from 'graftcode-instrumentation'
+
+export type LogAttributes = Record<string, string | number | boolean | undefined>
+
+export interface GraftCodeAppInsightsOptions {
+    serviceName: string
+    connectionString?: string
+    tracesPerSecond?: number
+    samplingRatio?: number
+    logLevel?: 'debug' | 'info' | 'warning' | 'error'
+    console?: boolean
+    graftcode?: GraftcodeInstrumentationConfig | false
+    instrumentations?: Instrumentation[]
+    azureMonitor?: AzureMonitorOpenTelemetryOptions
+}
+
+export interface GraftCodeAppLogger {
+    debug(message: string, attributes?: LogAttributes): void
+    info(message: string, attributes?: LogAttributes): void
+    warn(message: string, attributes?: LogAttributes): void
+    error(message: string, errorOrAttributes?: Error | LogAttributes): void
+}
+
+export interface GraftCodeTelemetry {
+    readonly serviceName: string
+    readonly isExporting: boolean
+    readonly tracer: Tracer
+    readonly logger: GraftCodeAppLogger
+    flush(): Promise<void>
+    shutdown(): Promise<void>
+}
+
+export declare function useGraftCodeAppInsights(options: GraftCodeAppInsightsOptions): GraftCodeTelemetry

package/src/index.js

@@ -0,0 +1,125 @@
+import { shutdownAzureMonitor, useAzureMonitor } from '@azure/monitor-opentelemetry'
+import { trace } from '@opentelemetry/api'
+import { logs } from '@opentelemetry/api-logs'
+import { registerInstrumentations } from '@opentelemetry/instrumentation'
+import { resourceFromAttributes } from '@opentelemetry/resources'
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node'
+import { GraftcodeInstrumentation } from 'graftcode-instrumentation'
+import { LogsLevel, parseLogsLevel } from 'hypertube-nodejs-sdk/abstractions'
+import { createAppLogger } from './appLogger.js'
+
+let active
+
+export function useGraftCodeAppInsights(options) {
+    const serviceName = options?.serviceName?.trim()
+    if (!serviceName) {
+        throw new TypeError('useGraftCodeAppInsights needs a serviceName')
+    }
+    if (active) {
+        if (active.serviceName === serviceName) {
+            return active
+        }
+        throw new Error(`GraftCode Application Insights telemetry is already started for ${active.serviceName}`)
+    }
+
+    const connectionString =
+        options.connectionString?.trim() || process.env.APPLICATIONINSIGHTS_CONNECTION_STRING?.trim() || undefined
+    const logLevel = parseLogsLevel(options.logLevel ?? 'info') ?? LogsLevel.Info
+    const stopProviders = connectionString
+        ? startAzureMonitor(serviceName, connectionString, options)
+        : startLocalTracing(serviceName)
+
+    const graftcode =
+        options.graftcode === false
+            ? []
+            : [new GraftcodeInstrumentation({ logLevel: options.logLevel ?? 'info', ...options.graftcode })]
+    const unregisterInstrumentations = registerInstrumentations({
+        instrumentations: [...graftcode, ...(options.instrumentations ?? [])],
+    })
+
+    let stopping
+    const telemetry = {
+        serviceName,
+        isExporting: connectionString !== undefined,
+        tracer: trace.getTracer(serviceName),
+        logger: createAppLogger(serviceName, logLevel, options.console !== false),
+        flush: forceFlush,
+        shutdown: () => {
+            stopping ??= (async () => {
+                process.off('beforeExit', onBeforeExit)
+                await forceFlush()
+                unregisterInstrumentations()
+                await stopProviders()
+                active = undefined
+            })()
+            return stopping
+        },
+    }
+    const onBeforeExit = () => {
+        void telemetry.shutdown()
+    }
+    process.once('beforeExit', onBeforeExit)
+
+    active = telemetry
+    if (!connectionString) {
+        telemetry.logger.warn(
+            `Application Insights telemetry for ${serviceName} is disabled: no connection string was configured. ` +
+                'Set APPLICATIONINSIGHTS_CONNECTION_STRING in this process or pass connectionString.'
+        )
+    }
+    return telemetry
+}
+
+function startAzureMonitor(serviceName, connectionString, options) {
+    const advanced = options.azureMonitor ?? {}
+    const http = advanced.instrumentationOptions?.http
+    const userIgnoreOutgoing = http?.ignoreOutgoingRequestHook
+
+    useAzureMonitor({
+        ...advanced,
+        azureMonitorExporterOptions: { ...advanced.azureMonitorExporterOptions, connectionString },
+        resource: resourceFromAttributes({ 'service.name': serviceName }),
+        tracesPerSecond: options.tracesPerSecond ?? 0,
+        samplingRatio: options.samplingRatio ?? 1,
+        instrumentationOptions: {
+            ...advanced.instrumentationOptions,
+            http: {
+                enabled: true,
+                ...http,
+                ignoreOutgoingRequestHook: (request) =>
+                    isWebSocketUpgrade(request) || Boolean(userIgnoreOutgoing?.(request)),
+            },
+        },
+    })
+    return () => shutdownAzureMonitor()
+}
+
+function startLocalTracing(serviceName) {
+    const provider = new NodeTracerProvider({ resource: resourceFromAttributes({ 'service.name': serviceName }) })
+    provider.register()
+    return () => provider.shutdown()
+}
+
+function isWebSocketUpgrade(request) {
+    const headers = request?.headers ?? {}
+    return Object.entries(headers).some(
+        ([name, value]) => name.toLowerCase() === 'upgrade' && String(value).toLowerCase() === 'websocket'
+    )
+}
+
+async function forceFlush() {
+    await Promise.allSettled([
+        delegateOf(trace.getTracerProvider())?.forceFlush?.(),
+        delegateOf(logs.getLoggerProvider())?.forceFlush?.(),
+    ])
+}
+
+function delegateOf(provider) {
+    if (typeof provider?.getDelegate === 'function') {
+        return provider.getDelegate()
+    }
+    if (typeof provider?._getDelegate === 'function') {
+        return provider._getDelegate()
+    }
+    return provider
+}