@senad-d/observme 0.1.0

package/src/query/grafana.ts

@@ -0,0 +1,371 @@
+import type { ObservMeConfig } from "../config/schema.ts";
+import { readDiagnosticMessage, sanitizeDiagnosticText } from "../diagnostics/sanitize.ts";
+import { assertNoSensitiveQueryInput } from "../safety/sensitive-input.ts";
+import type { GrafanaTransportClient, GrafanaTransportOptions } from "./grafana-transport.ts";
+import { createGrafanaTransport } from "./grafana-transport.ts";
+import type { GrafanaQueryDatasourceKey } from "./grafana-readiness.ts";
+import { formatGrafanaQueryReadiness, getGrafanaQueryReadiness } from "./grafana-readiness.ts";
+
+export type { GrafanaFetch } from "./grafana-transport.ts";
+export type GrafanaHealthCheckKind = "service" | "datasource";
+export type GrafanaHealthCheckStatus = "ok" | "failed" | "skipped";
+
+export interface GrafanaHealthCheckResult {
+  readonly label: string;
+  readonly kind: GrafanaHealthCheckKind;
+  readonly status: GrafanaHealthCheckStatus;
+  readonly detail?: string;
+}
+
+export interface GrafanaHealthResult {
+  readonly timeoutMs: number;
+  readonly checks: readonly GrafanaHealthCheckResult[];
+}
+
+export type GrafanaQueryClientOptions = GrafanaTransportOptions;
+
+interface GrafanaHealthTarget {
+  readonly label: string;
+  readonly kind: GrafanaHealthCheckKind;
+  readonly url: URL;
+  readonly fallbackUrl?: URL;
+}
+
+interface GrafanaDatasourceDefinition {
+  readonly label: string;
+  readonly key: GrafanaQueryDatasourceKey;
+  readonly uid: string;
+  readonly fallbackHealthPath?: string;
+}
+
+interface TraceTemplateReplacement {
+  readonly pattern: RegExp;
+  readonly key: TraceTemplateValueKey;
+}
+
+type TraceTemplateValueKey = "traceId" | "tempoDatasourceUid";
+
+type TraceTemplateValues = Record<TraceTemplateValueKey, string>;
+
+interface GrafanaExploreDatasourceRef {
+  readonly type: "tempo";
+  readonly uid: string;
+}
+
+interface GrafanaTraceQuery {
+  readonly refId: "A";
+  readonly datasource: GrafanaExploreDatasourceRef;
+  readonly queryType: "traceId";
+  readonly query: string;
+}
+
+interface GrafanaExplorePane {
+  readonly datasource: string;
+  readonly queries: readonly GrafanaTraceQuery[];
+  readonly range: {
+    readonly from: "now-1h";
+    readonly to: "now";
+  };
+}
+
+type GrafanaExplorePanes = Record<string, GrafanaExplorePane>;
+
+const traceIdPattern = /^[a-f0-9]{32}$/iu;
+const zeroTraceIdPattern = /^0{32}$/u;
+const traceIdTemplatePattern = /\{\{\s*traceId\s*\}\}|\{traceId\}|\$\{traceId\}|%TRACE_ID%/u;
+const fallbackTraceTemplateMarkerPattern = /\.\.\./u;
+const datasourceDefinitions = [
+  { label: "Tempo datasource", key: "tempo", fallbackHealthPath: "/ready" },
+  { label: "Loki datasource", key: "loki", fallbackHealthPath: undefined },
+  { label: "Metrics datasource", key: "prometheus", fallbackHealthPath: undefined },
+] as const;
+const traceTemplateReplacements: readonly TraceTemplateReplacement[] = [
+  { pattern: /\{\{\s*traceId\s*\}\}/gu, key: "traceId" },
+  { pattern: /\$\{traceId\}/gu, key: "traceId" },
+  { pattern: /\{traceId\}/gu, key: "traceId" },
+  { pattern: /%TRACE_ID%/gu, key: "traceId" },
+  { pattern: /\{\{\s*tempoDatasourceUid\s*\}\}/gu, key: "tempoDatasourceUid" },
+  { pattern: /\$\{tempoDatasourceUid\}/gu, key: "tempoDatasourceUid" },
+  { pattern: /\{tempoDatasourceUid\}/gu, key: "tempoDatasourceUid" },
+  { pattern: /%TEMPO_DATASOURCE_UID%/gu, key: "tempoDatasourceUid" },
+];
+
+export class GrafanaQueryClient {
+  readonly #config: ObservMeConfig;
+  readonly #transport: GrafanaTransportClient;
+
+  constructor(config: ObservMeConfig, options: GrafanaQueryClientOptions = {}) {
+    this.#config = config;
+    this.#transport = createGrafanaTransport(config, options);
+  }
+
+  async health(): Promise<GrafanaHealthResult> {
+    return getGrafanaHealthWithTransport(this.#config, this.#transport);
+  }
+
+  getTraceLink(traceId: string): string {
+    return getGrafanaTraceLink(this.#config, traceId);
+  }
+}
+
+export function createGrafanaQueryClient(
+  config: ObservMeConfig,
+  options: GrafanaQueryClientOptions = {},
+): GrafanaQueryClient {
+  return new GrafanaQueryClient(config, options);
+}
+
+export async function getGrafanaHealth(
+  config: ObservMeConfig,
+  options: GrafanaQueryClientOptions = {},
+): Promise<GrafanaHealthResult> {
+  return getGrafanaHealthWithTransport(config, createGrafanaTransport(config, options));
+}
+
+async function getGrafanaHealthWithTransport(
+  config: ObservMeConfig,
+  transport: GrafanaTransportClient,
+): Promise<GrafanaHealthResult> {
+  const checks = await Promise.all([
+    checkGrafanaReachability(config, transport),
+    ...createDatasourceDefinitions(config).map(datasource => checkDatasourceReachability(config, datasource, transport)),
+  ]);
+
+  return { timeoutMs: transport.timeoutMs, checks };
+}
+
+export function getGrafanaTraceLink(config: ObservMeConfig, traceId: string): string {
+  const normalizedTraceId = normalizeTraceId(traceId);
+  const template = config.query.links.traceUrlTemplate.trim();
+
+  if (hasTraceIdTemplatePlaceholder(template)) return renderTraceUrlTemplate(template, config, normalizedTraceId);
+  if (isFallbackTraceTemplate(template)) return buildDefaultGrafanaTraceLink(config, normalizedTraceId);
+
+  throw new Error("Grafana traceUrlTemplate must include a traceId placeholder or use the default Grafana link fallback.");
+}
+
+async function checkGrafanaReachability(
+  config: ObservMeConfig,
+  transport: GrafanaTransportClient,
+): Promise<GrafanaHealthCheckResult> {
+  const preflight = resolveGrafanaPreflightResult(config, "Grafana", "service");
+  if (preflight) return preflight;
+
+  try {
+    const target = createGrafanaHealthTarget(transport);
+    return await checkGrafanaTarget(target, transport);
+  } catch (error) {
+    return failedHealthResult("Grafana", "service", error);
+  }
+}
+
+async function checkDatasourceReachability(
+  config: ObservMeConfig,
+  datasource: GrafanaDatasourceDefinition,
+  transport: GrafanaTransportClient,
+): Promise<GrafanaHealthCheckResult> {
+  const preflight = resolveGrafanaPreflightResult(config, datasource.label, "datasource", datasource.key);
+  if (preflight) return preflight;
+
+  try {
+    const target = createDatasourceHealthTarget(transport, datasource);
+    return await checkGrafanaTarget(target, transport);
+  } catch (error) {
+    return failedHealthResult(datasource.label, "datasource", error);
+  }
+}
+
+async function checkGrafanaTarget(
+  target: GrafanaHealthTarget,
+  transport: GrafanaTransportClient,
+): Promise<GrafanaHealthCheckResult> {
+  try {
+    const response = await transport.fetch(target.url);
+    if (!shouldFetchGrafanaFallbackTarget(target, response)) return responseToHealthResult(target, response, transport);
+    return responseToHealthResult(target, await fetchGrafanaFallbackTarget(target, transport), transport);
+  } catch (error) {
+    return failedHealthResult(target.label, target.kind, error);
+  }
+}
+
+function createGrafanaHealthTarget(transport: GrafanaTransportClient): GrafanaHealthTarget {
+  return {
+    label: "Grafana",
+    kind: "service",
+    url: transport.apiUrl("/api/health"),
+  };
+}
+
+function createDatasourceHealthTarget(
+  transport: GrafanaTransportClient,
+  datasource: GrafanaDatasourceDefinition,
+): GrafanaHealthTarget {
+  return {
+    label: datasource.label,
+    kind: "datasource",
+    url: transport.datasourceApiUrl(datasource.uid, "/health"),
+    fallbackUrl: createDatasourceFallbackHealthUrl(transport, datasource),
+  };
+}
+
+function createDatasourceFallbackHealthUrl(
+  transport: GrafanaTransportClient,
+  datasource: GrafanaDatasourceDefinition,
+): URL | undefined {
+  if (!datasource.fallbackHealthPath) return undefined;
+
+  return transport.datasourceProxyUrl(datasource.uid, datasource.fallbackHealthPath);
+}
+
+function createDatasourceDefinitions(config: ObservMeConfig): GrafanaDatasourceDefinition[] {
+  return datasourceDefinitions.map(definition => ({
+    label: definition.label,
+    key: definition.key,
+    uid: config.query.grafana.datasourceUids[definition.key],
+    fallbackHealthPath: definition.fallbackHealthPath,
+  }));
+}
+
+function resolveGrafanaPreflightResult(
+  config: ObservMeConfig,
+  label: string,
+  kind: GrafanaHealthCheckKind,
+  datasourceKey?: GrafanaQueryDatasourceKey,
+): GrafanaHealthCheckResult | undefined {
+  const readiness = getGrafanaQueryReadiness(config, datasourceKey);
+  if (readiness.status === "ready") return undefined;
+  if (readiness.status === "disabled") return skippedHealthResult(label, kind, "query disabled");
+
+  return {
+    label,
+    kind,
+    status: "failed",
+    detail: formatGrafanaQueryReadiness(readiness),
+  };
+}
+
+function responseToHealthResult(
+  target: GrafanaHealthTarget,
+  response: Response,
+  transport: GrafanaTransportClient,
+): GrafanaHealthCheckResult {
+  if (response.ok) return { label: target.label, kind: target.kind, status: "ok" };
+
+  return {
+    label: target.label,
+    kind: target.kind,
+    status: "failed",
+    detail: transport.formatHttpFailure(response),
+  };
+}
+
+function shouldFetchGrafanaFallbackTarget(target: GrafanaHealthTarget, response: Response): boolean {
+  return target.kind === "datasource" && response.status === 404 && target.fallbackUrl !== undefined;
+}
+
+async function fetchGrafanaFallbackTarget(
+  target: GrafanaHealthTarget,
+  transport: GrafanaTransportClient,
+): Promise<Response> {
+  const fallbackUrl = target.fallbackUrl;
+  if (!fallbackUrl) throw new Error("Grafana datasource fallback health URL is not configured.");
+  return transport.fetch(fallbackUrl);
+}
+
+function failedHealthResult(label: string, kind: GrafanaHealthCheckKind, error: unknown): GrafanaHealthCheckResult {
+  return {
+    label,
+    kind,
+    status: "failed",
+    detail: formatHealthFailure(error),
+  };
+}
+
+function skippedHealthResult(label: string, kind: GrafanaHealthCheckKind, detail: string): GrafanaHealthCheckResult {
+  return { label, kind, status: "skipped", detail };
+}
+
+function buildDefaultGrafanaTraceLink(config: ObservMeConfig, traceId: string): string {
+  const baseUrl = config.query.grafana.url.trim();
+  if (!baseUrl) throw new Error("Grafana URL is not configured for trace-link construction.");
+
+  const url = new URL(baseUrl);
+  const basePath = removeTrailingSlashes(url.pathname);
+  url.pathname = `${basePath}/explore`;
+  url.search = "";
+  url.hash = "";
+  url.searchParams.set("schemaVersion", "1");
+  url.searchParams.set("panes", JSON.stringify(createDefaultExplorePanes(config, traceId)));
+  return url.toString();
+}
+
+function removeTrailingSlashes(value: string): string {
+  let end = value.length;
+  while (end > 0 && value[end - 1] === "/") end -= 1;
+  return value.slice(0, end);
+}
+
+function createDefaultExplorePanes(config: ObservMeConfig, traceId: string): GrafanaExplorePanes {
+  const tempoUid = config.query.grafana.datasourceUids.tempo;
+  return {
+    observmeTrace: {
+      datasource: tempoUid,
+      queries: [
+        {
+          refId: "A",
+          datasource: { type: "tempo", uid: tempoUid },
+          queryType: "traceId",
+          query: traceId,
+        },
+      ],
+      range: { from: "now-1h", to: "now" },
+    },
+  };
+}
+
+function renderTraceUrlTemplate(template: string, config: ObservMeConfig, traceId: string): string {
+  const values = createTraceTemplateValues(config, traceId);
+  let rendered = template;
+
+  for (const replacement of traceTemplateReplacements) {
+    rendered = rendered.replace(replacement.pattern, values[replacement.key]);
+  }
+
+  return rendered;
+}
+
+function createTraceTemplateValues(config: ObservMeConfig, traceId: string): TraceTemplateValues {
+  return {
+    traceId: encodeURIComponent(traceId),
+    tempoDatasourceUid: encodeURIComponent(config.query.grafana.datasourceUids.tempo),
+  };
+}
+
+function normalizeTraceId(traceId: string): string {
+  const trimmed = traceId.trim();
+  assertNoSensitiveQueryInput(trimmed, "Grafana traceId");
+
+  if (!traceIdPattern.test(trimmed) || zeroTraceIdPattern.test(trimmed)) {
+    throw new Error(
+      "Unsafe Grafana traceId: expected a non-zero 32-character hexadecimal OpenTelemetry trace id; raw prompts, commands, paths, and environment values are not query inputs.",
+    );
+  }
+
+  return trimmed.toLowerCase();
+}
+
+function hasTraceIdTemplatePlaceholder(template: string): boolean {
+  return traceIdTemplatePattern.test(template);
+}
+
+function isFallbackTraceTemplate(template: string): boolean {
+  return template === "" || fallbackTraceTemplateMarkerPattern.test(template);
+}
+
+function formatHealthFailure(error: unknown): string {
+  return formatError(error);
+}
+
+function formatError(error: unknown): string {
+  return sanitizeDiagnosticText(readDiagnosticMessage(error));
+}

package/src/query/loki.ts

@@ -0,0 +1,332 @@
+import type { ObservMeConfig } from "../config/schema.ts";
+import type { GrafanaFetch, GrafanaTransportClient } from "./grafana-transport.ts";
+import { createGrafanaTransport } from "./grafana-transport.ts";
+import { assertNoSensitiveQueryInput } from "../safety/sensitive-input.ts";
+import { assertGrafanaQueryReady } from "./grafana-readiness.ts";
+
+export type LokiFetch = GrafanaFetch;
+
+export interface TimeRange {
+  readonly from: Date;
+  readonly to: Date;
+}
+
+export interface LogResult {
+  readonly timestampUnixNano: string;
+  readonly line: string;
+  readonly labels: Record<string, string>;
+  readonly metadata?: Record<string, string>;
+}
+
+export interface LokiQueryClientOptions {
+  readonly fetch?: LokiFetch;
+}
+
+interface NormalizedTimeRange {
+  readonly from: Date;
+  readonly to: Date;
+}
+
+const minimumMaxLogs = 1;
+const maxLogQlQueryLength = 4096;
+const safeLokiAttributeNamePattern = /^[A-Za-z_][A-Za-z0-9_.]*$/u;
+const lokiIdentifierStartPattern = /^[A-Za-z_]$/u;
+const lokiIdentifierPartPattern = /^[A-Za-z0-9_.]$/u;
+
+export class LokiQueryClient {
+  readonly #config: ObservMeConfig;
+  readonly #transport: GrafanaTransportClient;
+
+  constructor(config: ObservMeConfig, options: LokiQueryClientOptions = {}) {
+    this.#config = config;
+    this.#transport = createGrafanaTransport(config, options);
+  }
+
+  async queryLoki(query: string, range: TimeRange): Promise<LogResult[]> {
+    return queryLokiWithTransport(this.#config, this.#transport, query, range);
+  }
+}
+
+export function createLokiQueryClient(
+  config: ObservMeConfig,
+  options: LokiQueryClientOptions = {},
+): LokiQueryClient {
+  return new LokiQueryClient(config, options);
+}
+
+export async function queryLoki(
+  config: ObservMeConfig,
+  query: string,
+  range: TimeRange,
+  options: LokiQueryClientOptions = {},
+): Promise<LogResult[]> {
+  return queryLokiWithTransport(config, createGrafanaTransport(config, options), query, range);
+}
+
+async function queryLokiWithTransport(
+  config: ObservMeConfig,
+  transport: GrafanaTransportClient,
+  query: string,
+  range: TimeRange,
+): Promise<LogResult[]> {
+  if (!config.query.enabled) return [];
+
+  assertGrafanaQueryReady(config, "loki");
+  const normalizedQuery = normalizeLokiQuery(query);
+  const timeRange = normalizeTimeRange(range);
+  const maxLogs = resolveMaxLogs(config);
+  const url = createLokiQueryRangeUrl(config, transport, normalizedQuery, timeRange, maxLogs);
+  const response = await transport.fetch(url, { timeoutMessage: "Loki query timed out." });
+
+  return readLokiLogResults(response, transport, maxLogs);
+}
+
+export function normalizeLokiAttributeName(attributeName: string): string {
+  const normalizedName = attributeName.trim();
+  if (!safeLokiAttributeNamePattern.test(normalizedName)) throw new Error(`Unsafe Loki attribute name: ${attributeName}`);
+  return normalizedName.replaceAll(".", "_");
+}
+
+export function normalizeLokiQueryAttributes(query: string): string {
+  let normalizedQuery = "";
+  let index = 0;
+  let quote: string | undefined;
+  let escaped = false;
+
+  while (index < query.length) {
+    const char = query[index];
+
+    if (quote) {
+      normalizedQuery += char;
+      quote = nextLokiQuote(quote, char, escaped);
+      escaped = nextLokiEscapeState(char, escaped);
+      index += 1;
+      continue;
+    }
+
+    if (isLokiQuote(char)) {
+      quote = char;
+      normalizedQuery += char;
+      index += 1;
+      continue;
+    }
+
+    if (isLokiIdentifierStart(char)) {
+      const token = readLokiIdentifier(query, index);
+      normalizedQuery += normalizeLokiQueryToken(token);
+      index += token.length;
+      continue;
+    }
+
+    normalizedQuery += char;
+    index += 1;
+  }
+
+  return normalizedQuery;
+}
+
+function nextLokiQuote(quote: string, char: string, escaped: boolean): string | undefined {
+  if (escaped || char !== quote) return quote;
+  return undefined;
+}
+
+function nextLokiEscapeState(char: string, escaped: boolean): boolean {
+  if (escaped) return false;
+  return char === "\\";
+}
+
+function normalizeLokiQuery(query: string): string {
+  const trimmed = query.trim();
+  if (!trimmed) throw new Error("Loki query requires a non-empty LogQL query.");
+  if (trimmed.length > maxLogQlQueryLength) throw new Error("Loki query is bounded to 4096 characters.");
+
+  assertNoSensitiveQueryInput(trimmed, "Loki query");
+  return normalizeLokiQueryAttributes(trimmed);
+}
+
+function normalizeLokiQueryToken(token: string): string {
+  return token.includes(".") ? normalizeLokiAttributeName(token) : token;
+}
+
+function readLokiIdentifier(query: string, start: number): string {
+  let end = start + 1;
+
+  while (end < query.length && isLokiIdentifierPart(query[end])) end += 1;
+  return query.slice(start, end);
+}
+
+function isLokiQuote(char: string): boolean {
+  return char === '"' || char === "'" || char === "`";
+}
+
+function isLokiIdentifierStart(char: string): boolean {
+  return lokiIdentifierStartPattern.test(char);
+}
+
+function isLokiIdentifierPart(char: string): boolean {
+  return lokiIdentifierPartPattern.test(char);
+}
+
+function normalizeTimeRange(range: TimeRange): NormalizedTimeRange {
+  const from = normalizeDate(range.from, "from");
+  const to = normalizeDate(range.to, "to");
+
+  if (from.getTime() > to.getTime()) throw new Error("Loki query range must have from <= to.");
+  return { from, to };
+}
+
+function normalizeDate(value: Date, label: string): Date {
+  if (!(value instanceof Date) || !Number.isFinite(value.getTime())) {
+    throw new TypeError(`Loki query range ${label} must be a valid Date.`);
+  }
+
+  return value;
+}
+
+function createLokiQueryRangeUrl(
+  config: ObservMeConfig,
+  transport: GrafanaTransportClient,
+  query: string,
+  range: NormalizedTimeRange,
+  maxLogs: number,
+): URL {
+  const url = transport.datasourceProxyUrl(config.query.grafana.datasourceUids.loki, "/loki/api/v1/query_range");
+
+  url.searchParams.set("query", query);
+  url.searchParams.set("start", formatEpochNanoseconds(range.from));
+  url.searchParams.set("end", formatEpochNanoseconds(range.to));
+  url.searchParams.set("limit", String(maxLogs));
+  url.searchParams.set("direction", "backward");
+  return url;
+}
+
+function formatEpochNanoseconds(date: Date): string {
+  return (BigInt(date.getTime()) * 1_000_000n).toString();
+}
+
+async function readLokiLogResults(
+  response: Response,
+  transport: GrafanaTransportClient,
+  maxLogs: number,
+): Promise<LogResult[]> {
+  if (!response.ok) throw new Error(`Loki query failed: ${transport.formatHttpFailure(response)}`);
+
+  const payload = (await response.json()) as unknown;
+  const apiError = readLokiApiError(payload);
+  if (apiError) throw new Error(`Loki query failed: ${apiError}`);
+
+  const logs = extractLokiLogResults(payload);
+  return logs.slice(0, maxLogs);
+}
+
+function readLokiApiError(payload: unknown): string | undefined {
+  if (!isRecord(payload) || payload.status !== "error") return undefined;
+
+  const errorType = readOptionalString(payload, "errorType");
+  const errorMessage = readOptionalString(payload, "error");
+  return [errorType, errorMessage].filter(isNonEmptyString).join(": ") || "unknown Loki API error";
+}
+
+function createLokiSchemaError(reason: string): Error {
+  return new Error(`Loki query failed: backend schema error: ${reason}.`);
+}
+
+function extractLokiLogResults(payload: unknown): LogResult[] {
+  const data = readLokiSuccessData(payload);
+  return extractLokiStreams(data.result).flatMap(toLogResultsFromStream);
+}
+
+function readLokiSuccessData(payload: unknown): Record<string, unknown> {
+  if (!isRecord(payload)) throw createLokiSchemaError("response must be a JSON object");
+  if (payload.status !== "success") throw createLokiSchemaError("status must be success");
+  if (!isRecord(payload.data)) throw createLokiSchemaError("data must be an object");
+  if (payload.data.resultType !== "streams") throw createLokiSchemaError("data.resultType must be streams");
+  return payload.data;
+}
+
+function extractLokiStreams(result: unknown): unknown[] {
+  if (!Array.isArray(result)) throw createLokiSchemaError("data.result must be an array of streams");
+  return result;
+}
+
+function toLogResultsFromStream(stream: unknown): LogResult[] {
+  if (!isRecord(stream)) throw createLokiSchemaError("each data.result stream must be an object");
+
+  const labels = readLokiStreamLabels(stream.stream);
+  const values = readLokiStreamValues(stream.values);
+  return values.map(value => toLogResult(value, labels));
+}
+
+function readLokiStreamLabels(value: unknown): Record<string, string> {
+  if (!isRecord(value)) throw createLokiSchemaError("each data.result stream labels must be an object");
+  return readStringRecord(value);
+}
+
+function readLokiStreamValues(value: unknown): unknown[] {
+  if (!Array.isArray(value)) throw createLokiSchemaError("each data.result stream values must be an array");
+  if (value.length === 0) throw createLokiSchemaError("each data.result stream values array must include at least one log entry");
+  return value;
+}
+
+function toLogResult(value: unknown, labels: Record<string, string>): LogResult {
+  if (!Array.isArray(value) || value.length < 2) throw createLokiSchemaError("Loki log values must be [timestamp, line] pairs");
+
+  const timestampUnixNano = readNonEmptyStringOrNumber(value[0]);
+  const line = readStringOrNumber(value[1]);
+  if (!timestampUnixNano || line === undefined) throw createLokiSchemaError("Loki log values must include timestamp and line strings");
+
+  const metadata = readLokiMetadata(value[2]);
+  const result = { timestampUnixNano, line, labels: { ...labels } };
+  return Object.keys(metadata).length > 0 ? { ...result, metadata } : result;
+}
+
+function readLokiMetadata(value: unknown): Record<string, string> {
+  if (value === undefined) return {};
+  if (!isRecord(value)) throw createLokiSchemaError("Loki log metadata must be an object when present");
+  return readStringRecord(value);
+}
+
+function readStringRecord(value: unknown): Record<string, string> {
+  const record: Record<string, string> = {};
+  if (!isRecord(value)) return record;
+
+  for (const [key, item] of Object.entries(value)) {
+    const text = readStringOrNumber(item);
+    if (text !== undefined) record[key] = text;
+  }
+
+  return record;
+}
+
+function readOptionalString(item: Record<string, unknown>, key: string): string | undefined {
+  const value = item[key];
+  if (typeof value !== "string") return undefined;
+
+  const trimmed = value.trim();
+  return trimmed || undefined;
+}
+
+function readNonEmptyStringOrNumber(value: unknown): string | undefined {
+  const text = readStringOrNumber(value)?.trim();
+  return text || undefined;
+}
+
+function readStringOrNumber(value: unknown): string | undefined {
+  if (typeof value === "string") return value;
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  return undefined;
+}
+
+function isNonEmptyString(value: string | undefined): value is string {
+  return value !== undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function resolveMaxLogs(config: ObservMeConfig): number {
+  const maxLogs = config.query.maxLogs;
+  if (!Number.isFinite(maxLogs) || maxLogs < minimumMaxLogs) return minimumMaxLogs;
+  return Math.trunc(maxLogs);
+}