@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 +53 -0
- package/lib/index.cjs +229 -1
- package/lib/index.cjs.map +1 -1
- package/lib/index.d.cts +117 -5
- package/lib/index.d.ts +117 -5
- package/lib/index.js +223 -2
- package/lib/index.js.map +1 -1
- package/lib/{query-CofVHbt1.d.cts → query-BYQW0k9P.d.cts} +2 -2
- package/lib/{query-CofVHbt1.d.ts → query-BYQW0k9P.d.ts} +2 -2
- package/package.json +2 -1
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.
|
|
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
|