@kevsjh/cloud-trace-logger 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 kevsjh
+
+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

@@ -0,0 +1,103 @@
+# @kevsjh/cloud-trace-logger
+
+Structured JSON logger for Google Cloud. Correlates logs with [Cloud Trace](https://cloud.google.com/trace) and annotates errors for [Cloud Error Reporting](https://cloud.google.com/error-reporting) — zero dependencies.
+
+## Install
+
+```bash
+bun add @kevsjh/cloud-trace-logger
+# or
+npm install @kevsjh/cloud-trace-logger
+```
+
+## Usage
+
+```ts
+import { createCloudTraceLogger } from "@kevsjh/cloud-trace-logger";
+
+const log = createCloudTraceLogger({ projectId: "my-project" });
+
+log({ message: "Server started", severity: "INFO" });
+```
+
+### With request tracing (Express, Fastify, etc.)
+
+Pass the request object to correlate logs with Cloud Trace:
+
+```ts
+app.get("/", (req, res) => {
+  log({ message: "Handling request", req });
+  res.send("ok");
+});
+```
+
+The logger reads the `x-cloud-trace-context` header and adds the `logging.googleapis.com/trace` field automatically.
+
+### With error reporting
+
+```ts
+try {
+  await doSomething();
+} catch (err) {
+  log({ message: "doSomething failed", severity: "ERROR", error: err });
+}
+```
+
+In production, errors are annotated with the Cloud Error Reporting `@type` so they appear in the Error Reporting console.
+
+### With structured data
+
+```ts
+log({ message: "User signed up", data: { userId: "abc", plan: "pro" } });
+```
+
+Data fields are spread into the top-level log entry.
+
+## Configuration
+
+```ts
+const log = createCloudTraceLogger({
+  // Google Cloud project ID.
+  // Falls back to PROJECT_ID or GOOGLE_CLOUD_PROJECT env vars.
+  projectId: "my-project",
+
+  // Suppress DEBUG logs. Defaults to true when NODE_ENV=production.
+  suppressDebug: true,
+
+  // Add Cloud Error Reporting @type on error-class severities.
+  // Defaults to true when NODE_ENV=production.
+  errorReporting: true,
+});
+```
+
+All options are optional — env vars are used as defaults.
+
+## Severity levels
+
+All [Google Cloud Logging severity levels](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#LogSeverity) are supported:
+
+`DEBUG` | `INFO` | `WARNING` | `ERROR` | `CRITICAL` | `ALERT` | `EMERGENCY`
+
+`WARN` is accepted as an alias for `WARNING`.
+
+## Output
+
+Each call writes a single JSON line to stdout via `console.log`, which Cloud Logging picks up automatically on Cloud Run, Cloud Functions, and GKE.
+
+```json
+{
+  "logging.googleapis.com/trace": "projects/my-project/traces/abc123",
+  "severity": "ERROR",
+  "message": "doSomething failed",
+  "error": {
+    "errorMessage": "connection refused",
+    "errorStack": "Error: connection refused\n    at ...",
+    "errorName": "Error"
+  },
+  "@type": "type.googleapis.com/google.devtools.clouderrorreporting.v1beta1.ReportedErrorEvent"
+}
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+export type Severity = "DEBUG" | "INFO" | "WARNING" | "WARN" | "ERROR" | "CRITICAL" | "ALERT" | "EMERGENCY";
+export type LoggableRequest = {
+    headers: Record<string, string | string[] | undefined>;
+};
+export type LoggerOptions = {
+    /** Google Cloud project ID. Falls back to PROJECT_ID then GOOGLE_CLOUD_PROJECT env vars. */
+    projectId?: string;
+    /** Suppress DEBUG-level logs. Defaults to true when NODE_ENV === "production". */
+    suppressDebug?: boolean;
+    /** Add Cloud Error Reporting @type on error-class severities. Defaults to true when NODE_ENV === "production". */
+    errorReporting?: boolean;
+};
+export type LogOptions = {
+    message: string;
+    req?: LoggableRequest;
+    severity?: Severity;
+    data?: Record<string, any> | string;
+    error?: unknown;
+};
+export declare function createCloudTraceLogger(options?: LoggerOptions): ({ message, req, severity, data, error, }: LogOptions) => void;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAChB,OAAO,GACP,MAAM,GACN,SAAS,GACT,MAAM,GACN,OAAO,GACP,UAAU,GACV,OAAO,GACP,WAAW,CAAC;AAEhB,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;CACxD,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,4FAA4F;IAC5F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kFAAkF;IAClF,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kHAAkH;IAClH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,eAAe,CAAC;IACtB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC;IACpC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAIF,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,aAAkB,IAY5C,0CAMjB,UAAU,KAAG,IAAI,CAwErB"}

package/dist/index.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCloudTraceLogger = createCloudTraceLogger;
+const ERROR_SEVERITIES = ["ERROR", "CRITICAL", "ALERT", "EMERGENCY"];
+function createCloudTraceLogger(options = {}) {
+    const projectId = options.projectId ??
+        process.env.PROJECT_ID ??
+        process.env.GOOGLE_CLOUD_PROJECT;
+    const suppressDebug = options.suppressDebug ?? process.env.NODE_ENV === "production";
+    const errorReporting = options.errorReporting ?? process.env.NODE_ENV === "production";
+    return function log({ message, req, severity = "INFO", data, error, }) {
+        try {
+            const normalizedSeverity = severity === "WARN" ? "WARNING" : severity;
+            if (suppressDebug && normalizedSeverity === "DEBUG") {
+                return;
+            }
+            // Trace extraction
+            let trace;
+            if (req && projectId) {
+                const traceHeader = req.headers["x-cloud-trace-context"] ??
+                    req.headers["X-Cloud-Trace-Context"];
+                if (traceHeader) {
+                    const traceValue = Array.isArray(traceHeader)
+                        ? traceHeader[0]
+                        : traceHeader;
+                    const traceId = traceValue?.split("/")[0];
+                    if (traceId) {
+                        trace = `projects/${projectId}/traces/${traceId}`;
+                    }
+                }
+            }
+            // Data normalization
+            const dataFields = data === undefined
+                ? {}
+                : typeof data === "object" && data !== null && !Array.isArray(data)
+                    ? data
+                    : { payload: data };
+            // Error serialization
+            const errorFields = error === undefined
+                ? undefined
+                : error instanceof Error
+                    ? {
+                        errorMessage: error.message,
+                        errorStack: error.stack,
+                        errorName: error.name,
+                    }
+                    : { errorValue: String(error) };
+            const entry = {
+                ...(trace && { "logging.googleapis.com/trace": trace }),
+                ...dataFields,
+                ...(errorFields && { error: errorFields }),
+                severity: normalizedSeverity,
+                message,
+                ...(errorReporting &&
+                    ERROR_SEVERITIES.includes(normalizedSeverity) && {
+                    "@type": "type.googleapis.com/google.devtools.clouderrorreporting.v1beta1.ReportedErrorEvent",
+                }),
+            };
+            console.log(JSON.stringify(entry));
+        }
+        catch (err) {
+            console.error(JSON.stringify({
+                loggingInternalError: `Error during logging execution: ${err instanceof Error ? err.message : String(err)}`,
+                originalSeverity: severity,
+                originalMessage: message,
+                severity: "ERROR",
+            }));
+        }
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@kevsjh/cloud-trace-logger",
+  "version": "0.0.1",
+  "description": "Structured JSON logger with Google Cloud Trace correlation and Cloud Error Reporting support",
+  "author": "kevsjh",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kevsjh/cloud-trace-logger"
+  },
+  "keywords": [
+    "google-cloud",
+    "cloud-trace",
+    "structured-logging",
+    "cloud-run",
+    "cloud-error-reporting"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "dev": "tsc -w",
+    "prepublishOnly": "bun run clean && bun run build"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.24",
+    "typescript": "^5.0.0"
+  }
+}