@grow-codes/grafana-loki 0.1.1 → 0.2.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/AGENTS.md ADDED
@@ -0,0 +1,53 @@
1
+ <!-- Generated by sdk-kit 0.3.0 — do not edit; change sdk-kit and run "sdk-kit sync" -->
2
+
3
+ # `@grow-codes/grafana-loki` — agent quickstart (TypeScript)
4
+
5
+ Ships inside the npm package (`node_modules/@grow-codes/grafana-loki/AGENTS.md`). Use it instead of reading
6
+ the package source. Full docs: https://grow-codes-packages.github.io/grafana-loki/ · Service:
7
+ Grafana Loki · Categories: logging.
8
+
9
+ ```sh
10
+ npm i @grow-codes/grafana-loki # Node >= 22.12; ESM and CommonJS
11
+ ```
12
+
13
+ ## Client
14
+
15
+ ```ts
16
+ import { LokiClient, LokiConfig, isGrowError } from "@grow-codes/grafana-loki";
17
+ const client = LokiClient.fromEnv(); // GROW_GRAFANA_LOKI_* > vendor env > defaults
18
+ await client.health(); // never throws for a down service
19
+ await client.close(); // idempotent; flushes batches
20
+ ```
21
+
22
+ Config precedence: explicit option > `GROW_GRAFANA_LOKI_<NAME>` > vendor variables > default. Common names:
23
+ `URL`, `TOKEN`, `CONNECT_TIMEOUT`, `REQUEST_TIMEOUT`, `TOTAL_TIMEOUT`, `MAX_RETRIES`, `CA_CERT`, `PROXY`.
24
+ Errors: `LokiError` with `code` (`CONFIG`, `AUTHENTICATION`, `PERMISSION_DENIED`, `NOT_FOUND`, `CONFLICT`,
25
+ `RATE_LIMITED`, `VALIDATION`, `UNAVAILABLE`, `TIMEOUT`, `UNSUPPORTED`, `CANCELLED`), `retryable`, `httpStatus`.
26
+ Branch on `code`, never on the message. Credentials are `Secret`; never log `reveal()` results.
27
+
28
+ ## Logging: one call
29
+
30
+ ```ts
31
+ import { initLogging, requestLogger } from "@grow-codes/grafana-loki";
32
+ const { logger, flush, close, canary } = initLogging({ service: "orders" }); // after loadConfig()
33
+ logger.info("started", { port: 3000 });
34
+ app.use(requestLogger()); // Express / NestJS: x-request-id + "request completed"
35
+ process.on("SIGTERM", () => void close());
36
+ ```
37
+
38
+ - `initLogging(opts?: { service?: string; level?: string; stdout?: boolean; ship?: boolean;
39
+ redaction?: RedactionOptions }): LoggingHandle` — idempotent per process (`getLogging()` returns it).
40
+ - Always writes JSON lines to stdout: `time`, `level`, `msg`, `service`, `environment`, `request_id`,
41
+ `trace_id`, `span_id`, attributes (redacted). When `GROW_LOGGING_PROVIDER=grafana-loki` it also ships through
42
+ this package (config from `GROW_GRAFANA_LOKI_*`) and marks lines `log_shipped:"sdk"`; records the SDK
43
+ could not export are re-emitted with `log_shipped:"sdk_failed"`. Never throws for a down service.
44
+ - Service name: `GROW_SERVICE_NAME` > `OTEL_SERVICE_NAME`; environment: `GROW_ENVIRONMENT`; level: `LOG_LEVEL`.
45
+ - Handle: `logger` (`trace…fatal(message, attributes?)`, `child(attrs)`), `logs` (SDK `LogClient` or
46
+ `undefined`), `shipped`, `flush(timeoutMs?)`, `close()`, `canary(message, attrs?)` (SDK only),
47
+ `pinoStream()` (pass to `pino(opts, stream)`).
48
+ - `withRequestId(id, fn)`, `currentRequestId()`; pino/winston transports: `createPinoTransport(logs)`,
49
+ `new WinstonTransport({ client: logs })`.
50
+
51
+ ## Testing
52
+
53
+ `@grow-codes/grafana-loki/testing`: in-memory fakes (`InMemorySecretsProvider`, `MemoryLogExporter`, …).
package/lib/index.cjs CHANGED
@@ -6,6 +6,8 @@ var undici = require('undici');
6
6
  var zlib = require('zlib');
7
7
  var api = require('@opentelemetry/api');
8
8
  var stream = require('stream');
9
+ var async_hooks = require('async_hooks');
10
+ var crypto = require('crypto');
9
11
  var snappyjs = require('snappyjs');
10
12
  var WebSocket = require('ws');
11
13
 
@@ -608,7 +610,7 @@ function secretValues(...values) {
608
610
  }
609
611
 
610
612
  // src/core/version.ts
611
- var SDK_VERSION = "0.1.1";
613
+ var SDK_VERSION = "0.2.0";
612
614
  var PACKAGE_KEY = "grafana-loki";
613
615
  var LANGUAGE = "typescript";
614
616
  var SDK_KIT_VERSION = "0.3.0";
@@ -2042,6 +2044,225 @@ var WinstonTransport = class extends stream.Writable {
2042
2044
  }
2043
2045
  };
2044
2046
 
2047
+ // src/logging-connect.ts
2048
+ var connectLogClient = ({
2049
+ resource,
2050
+ onDropped
2051
+ }) => {
2052
+ const client = LokiClient.fromEnv();
2053
+ const factory = client.logClient;
2054
+ if (typeof factory !== "function") {
2055
+ void client.close();
2056
+ return void 0;
2057
+ }
2058
+ const logs = factory.call(client, { resource, batch: { onDrop: onDropped } });
2059
+ return {
2060
+ logs,
2061
+ close: async () => {
2062
+ await logs.close();
2063
+ await client.close();
2064
+ }
2065
+ };
2066
+ };
2067
+
2068
+ // src/logging/init.ts
2069
+ var LOG_SHIPPED_FIELD = "log_shipped";
2070
+ var requestContext = new async_hooks.AsyncLocalStorage();
2071
+ var GLOBAL_KEY = /* @__PURE__ */ Symbol.for(`grow-codes.${PACKAGE_KEY}.logging`);
2072
+ function withRequestId(requestId, fn) {
2073
+ return requestContext.run({ requestId }, fn);
2074
+ }
2075
+ function currentRequestId() {
2076
+ return requestContext.getStore()?.requestId;
2077
+ }
2078
+ function getLogging() {
2079
+ return globalThis[GLOBAL_KEY];
2080
+ }
2081
+ function first(env, ...names) {
2082
+ for (const name of names) {
2083
+ const value = env[name]?.trim();
2084
+ if (value !== void 0 && value !== "") return value;
2085
+ }
2086
+ return void 0;
2087
+ }
2088
+ function stdoutLine(record, marker) {
2089
+ const line = {
2090
+ time: record.timestamp.toISOString(),
2091
+ level: chunkVGAJJR3M_cjs.severityText(record.severity).toLowerCase(),
2092
+ msg: record.body
2093
+ };
2094
+ const resource = record.resource;
2095
+ if (resource["service.name"] !== void 0) line["service"] = resource["service.name"];
2096
+ if (resource["deployment.environment"] !== void 0)
2097
+ line["environment"] = resource["deployment.environment"];
2098
+ if (record.traceId !== void 0) line["trace_id"] = record.traceId;
2099
+ if (record.spanId !== void 0) line["span_id"] = record.spanId;
2100
+ for (const [key, value] of Object.entries(record.attributes)) if (!(key in line)) line[key] = value;
2101
+ if (marker !== void 0) line[LOG_SHIPPED_FIELD] = marker;
2102
+ return JSON.stringify(line);
2103
+ }
2104
+ function initLogging(opts = {}) {
2105
+ const existing = getLogging();
2106
+ if (existing !== void 0) return existing;
2107
+ const env = opts.env ?? process.env;
2108
+ const service = opts.service ?? first(env, "GROW_SERVICE_NAME", "OTEL_SERVICE_NAME") ?? "unknown_service";
2109
+ const environment = first(env, "GROW_ENVIRONMENT", "DEPLOYMENT_ENVIRONMENT");
2110
+ const resource = { "service.name": service };
2111
+ if (environment !== void 0) resource["deployment.environment"] = environment;
2112
+ const levelText = opts.level ?? first(env, "LOG_LEVEL", "GROW_LOG_LEVEL") ?? "info";
2113
+ const minSeverity = chunkVGAJJR3M_cjs.parseSeverity(levelText) ?? 9 /* Info */;
2114
+ const write = opts.write ?? ((line) => void process.stdout.write(`${line}
2115
+ `));
2116
+ const redaction = new RedactionProcessor(opts.redaction ?? {});
2117
+ const ship = opts.ship ?? first(env, "GROW_LOGGING_PROVIDER") === PACKAGE_KEY;
2118
+ let connection;
2119
+ if (ship) {
2120
+ try {
2121
+ const onDropped = (records) => {
2122
+ for (const record of records) {
2123
+ try {
2124
+ write(stdoutLine(record, "sdk_failed"));
2125
+ } catch {
2126
+ }
2127
+ }
2128
+ };
2129
+ connection = (opts.connect ?? connectLogClient)({ resource, env, onDropped });
2130
+ } catch (err) {
2131
+ write(
2132
+ stdoutLine(
2133
+ {
2134
+ timestamp: /* @__PURE__ */ new Date(),
2135
+ severity: 13 /* Warn */,
2136
+ body: `logging: ${PACKAGE_KEY} transport not available, stdout only (${err.name})`,
2137
+ attributes: {},
2138
+ resource
2139
+ }
2140
+ )
2141
+ );
2142
+ }
2143
+ }
2144
+ const logs = connection?.logs;
2145
+ const shipped = logs !== void 0;
2146
+ const toStdout = opts.stdout ?? true;
2147
+ const sink = {
2148
+ send(input) {
2149
+ const requestId = currentRequestId();
2150
+ const attributes = chunkVGAJJR3M_cjs.toAttributes({
2151
+ ...requestId === void 0 ? {} : { request_id: requestId },
2152
+ ...input.attributes
2153
+ });
2154
+ const severity = input.severity ?? 9 /* Info */;
2155
+ const record = {
2156
+ timestamp: input.timestamp ?? /* @__PURE__ */ new Date(),
2157
+ severity,
2158
+ severityText: chunkVGAJJR3M_cjs.severityText(severity),
2159
+ body: input.message,
2160
+ attributes,
2161
+ resource
2162
+ };
2163
+ if (input.traceId !== void 0) record.traceId = input.traceId;
2164
+ if (input.spanId !== void 0) record.spanId = input.spanId;
2165
+ if (input.traceFlags !== void 0) record.traceFlags = input.traceFlags;
2166
+ if (toStdout) {
2167
+ try {
2168
+ write(stdoutLine(redaction.process(record), shipped ? "sdk" : void 0));
2169
+ } catch {
2170
+ }
2171
+ }
2172
+ logs?.send(record);
2173
+ }
2174
+ };
2175
+ let closing;
2176
+ const handle = {
2177
+ logger: new Logger(sink, { minSeverity }),
2178
+ logs,
2179
+ shipped,
2180
+ service,
2181
+ flush: (timeoutMs) => logs === void 0 ? Promise.resolve() : logs.flush(timeoutMs),
2182
+ close: () => {
2183
+ closing ??= (async () => {
2184
+ if (globalThis[GLOBAL_KEY] === handle) globalThis[GLOBAL_KEY] = void 0;
2185
+ await connection?.close();
2186
+ })();
2187
+ return closing;
2188
+ },
2189
+ canary: async (message, attributes = {}) => {
2190
+ if (logs === void 0) return false;
2191
+ logs.send({ message, severity: 9 /* Info */, attributes: { "foundation.canary": true, ...attributes } });
2192
+ await logs.flush(5e3).catch(() => void 0);
2193
+ return true;
2194
+ },
2195
+ pinoStream: () => pinoTee(write, logs, shipped, toStdout)
2196
+ };
2197
+ globalThis[GLOBAL_KEY] = handle;
2198
+ return handle;
2199
+ }
2200
+ function pinoTee(write, logs, shipped, toStdout) {
2201
+ const transport = logs === void 0 ? void 0 : createPinoTransport(logs, { flushOnEnd: false });
2202
+ return new stream.Writable({
2203
+ write(chunk, _encoding, callback) {
2204
+ const text = chunk.toString();
2205
+ if (toStdout) {
2206
+ for (const raw of text.split("\n")) {
2207
+ if (raw.trim() === "") continue;
2208
+ let out = raw;
2209
+ if (shipped) {
2210
+ try {
2211
+ out = JSON.stringify({ ...JSON.parse(raw), [LOG_SHIPPED_FIELD]: "sdk" });
2212
+ } catch {
2213
+ }
2214
+ }
2215
+ write(out);
2216
+ }
2217
+ }
2218
+ if (transport === void 0) callback();
2219
+ else transport.write(chunk, callback);
2220
+ },
2221
+ final(callback) {
2222
+ if (transport === void 0) callback();
2223
+ else transport.end(callback);
2224
+ }
2225
+ });
2226
+ }
2227
+ function headerValue(value) {
2228
+ const v = Array.isArray(value) ? value[0] : value;
2229
+ return v === void 0 || v.trim() === "" ? void 0 : v.trim().slice(0, 128);
2230
+ }
2231
+ function requestLogger(opts = {}) {
2232
+ const header = (opts.header ?? "x-request-id").toLowerCase();
2233
+ const skip = opts.skip ?? ["/health/live", "/health/ready"];
2234
+ return (req, res, next) => {
2235
+ const requestId = headerValue(req.headers[header]) ?? crypto.randomUUID();
2236
+ res.setHeader(header, requestId);
2237
+ const path = (req.originalUrl ?? req.url ?? "/").split("?")[0] ?? "/";
2238
+ const start = performance.now();
2239
+ if (!skip.some((p) => path.startsWith(p))) {
2240
+ let done = false;
2241
+ const finish = () => {
2242
+ if (done) return;
2243
+ done = true;
2244
+ const logger = opts.logger ?? getLogging()?.logger;
2245
+ const status = res.statusCode;
2246
+ const attributes = {
2247
+ request_id: requestId,
2248
+ "http.method": req.method ?? "GET",
2249
+ "http.route": path,
2250
+ "http.status_code": status,
2251
+ duration_ms: Math.round((performance.now() - start) * 100) / 100
2252
+ };
2253
+ if (status >= 500) logger?.error("request completed", attributes);
2254
+ else if (status >= 400) logger?.warn("request completed", attributes);
2255
+ else logger?.info("request completed", attributes);
2256
+ };
2257
+ res.once("finish", finish);
2258
+ res.once("close", finish);
2259
+ }
2260
+ withRequestId(requestId, () => {
2261
+ next();
2262
+ });
2263
+ };
2264
+ }
2265
+
2045
2266
  // src/time.ts
2046
2267
  var NS_PER_MS = 1000000n;
2047
2268
  var DIGITS = /^\d+$/;
@@ -3800,6 +4021,7 @@ exports.EnvReader = EnvReader;
3800
4021
  exports.HttpTransport = HttpTransport;
3801
4022
  exports.LABEL_NAME_PATTERN = LABEL_NAME_PATTERN;
3802
4023
  exports.LANGUAGE = LANGUAGE;
4024
+ exports.LOG_SHIPPED_FIELD = LOG_SHIPPED_FIELD;
3803
4025
  exports.LogQL = LogQL;
3804
4026
  exports.Logger = Logger;
3805
4027
  exports.LokiClient = LokiClient;
@@ -3827,6 +4049,7 @@ exports.WinstonTransport = WinstonTransport;
3827
4049
  exports.attrToString = attrToString;
3828
4050
  exports.createDispatcher = createDispatcher;
3829
4051
  exports.createPinoTransport = createPinoTransport;
4052
+ exports.currentRequestId = currentRequestId;
3830
4053
  exports.dateToNanos = dateToNanos;
3831
4054
  exports.decodeBuildInfo = decodeBuildInfo;
3832
4055
  exports.decodeCursor = decodeCursor;
@@ -3844,7 +4067,9 @@ exports.encodeCursor = encodeCursor;
3844
4067
  exports.encodePushRequest = encodePushRequest;
3845
4068
  exports.entryToLogRecord = entryToLogRecord;
3846
4069
  exports.formatLabelSet = formatLabelSet;
4070
+ exports.getLogging = getLogging;
3847
4071
  exports.healthStatus = healthStatus;
4072
+ exports.initLogging = initLogging;
3848
4073
  exports.isHealthyWord = isHealthyWord;
3849
4074
  exports.isIdempotentMethod = isIdempotentMethod;
3850
4075
  exports.isRetryableStatus = isRetryableStatus;
@@ -3874,6 +4099,7 @@ exports.redactHeaders = redactHeaders;
3874
4099
  exports.redactSecretsInText = redactSecretsInText;
3875
4100
  exports.redactText = redactText;
3876
4101
  exports.redactUrl = redactUrl;
4102
+ exports.requestLogger = requestLogger;
3877
4103
  exports.resolveBatchOptions = resolveBatchOptions;
3878
4104
  exports.resolveCommonConfig = resolveCommonConfig;
3879
4105
  exports.safeCall = safeCall;
@@ -3882,6 +4108,7 @@ exports.secondsToDate = secondsToDate;
3882
4108
  exports.secretValues = secretValues;
3883
4109
  exports.silentLogger = silentLogger;
3884
4110
  exports.snappyCompress = snappyCompress;
4111
+ exports.stdoutLine = stdoutLine;
3885
4112
  exports.stringMap = stringMap;
3886
4113
  exports.tenantIdProblem = tenantIdProblem;
3887
4114
  exports.toNanos = toNanos;
@@ -3891,5 +4118,6 @@ exports.validateCommonConfig = validateCommonConfig;
3891
4118
  exports.validateLabelName = validateLabelName;
3892
4119
  exports.validateLabels = validateLabels;
3893
4120
  exports.winstonLevelToSeverity = winstonLevelToSeverity;
4121
+ exports.withRequestId = withRequestId;
3894
4122
  //# sourceMappingURL=index.cjs.map
3895
4123
  //# sourceMappingURL=index.cjs.map