SigNozStore — SigNoz OTLP log ingest & query

SigNozStore — SigNoz OTLP log ingest & query Overview SigNoz is an open-source, ClickHouse-backed observability platform for logs, traces, and metrics. Logs are ingested over OTLP/HTTP (the OpenTelemetry logs protocol) and queried through SigNoz's query-range API (a builder-style JSON body over its ClickHouse store). There is no SQL-shaped query surface exposed to clients, no row-level UPDATE/DELETE, and no identifier escaping, so SigNoz does not fit the SQL Dialect interface (src/dialects/dialect.ts). SigNozStore therefore implements the minimal NoSqlStore marker interface (src/nosql/store.ts) — connection lifecycle plus a getClient() escape hatch — and exposes SigNoz's OTLP/HTTP log ingest and its query-range API (plus log-field and service metadata) directly. Identity: Property | Value | --------- | ------------ | name | 'signoz' | library | 'fetch' | No canonical driver — HTTP over fetch SigNoz has no single canonical npm client; ingest is OTLP/HTTP JSON and query is a REST/JSON API. This store talks to both with the global fetch (so library is 'fetch'). When no client is injected, an internal client over fetch + baseURL is built at connect() time by createFetchClient(baseURL, headers) (its GET sends Accept: application/json). Injected client SigNozStoreOptions accepts a pre-built client implementing the SigNozHttpClient interface. When provided it is used verbatim and baseURL is ignored — this is how the test suite injects a mock (no network). Connection Option | Type | Purpose | --------- | ------------------------ | -------------------------------------------------------------------------- | baseURL | string | Base URL of the SigNoz query service. Defaults to http://localhost:8080. | client | SigNozHttpClient | Pre-built HTTP client. When set, baseURL is ignored. | headers | Record<string, string> | Extra HTTP headers (e.g. SIGNOZ-API-KEY) sent with every request. | Injected-client form Methods Metadata reads route through an internal doGet, which wraps any client failure in a DatabaseError. Calling a method before connect() (or after disconnect()) throws a ConnectionError. Lifecycle Method | Signature | Behavior | ------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------- | connect | connect(): Promise<void> | Uses an injected client if provided, otherwise builds a fetch client from baseURL. Idempotent. | disconnect | disconnect(): Promise<void> | Clears the client and connection state. | isConnected | isConnected(): boolean | true only when connected and a client is present. | getClient | getClient(): SigNozHttpClient | Returns the underlying (internal or injected) client. Throws ConnectionError if not connected. | Ingest / query / metadata Method | Signature | Endpoint | Behavior | --------- | ----------------------------------------------------------------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------- | push | push(resource: Record<string, string \| number \| boolean>, entries: SigNozLogEntry[]): Promise<any> | POST /v1/logs | Ingests log records over OTLP/HTTP. Entries are assembled into the OTLP resourceLogs → scopeLogs → logRecords envelope, tagged with the shared resource attributes. Values are mapped to OTLP AnyValues (int/double/bool/string). | query | query(builder: Record<string, unknown>, options?: SigNozQueryOptions): Promise<any> | POST /api/v4/queryrange | Runs a query-range request. The builder is SigNoz's composite query payload; start/end/step are merged in as the time window. Returns the parsed response. | labels | labels(): Promise<any> | GET /api/v1/logs/fields | Lists the known log field/attribute keys. | streams | streams(): Promise<any> | GET /api/v1/services | Lists the observed services. | Option / entry shapes A numeric attribute becomes { intValue } when integral or { doubleValue } otherwise; a boolean becomes { boolValue }; everything else { stringValue }. Example Verification status Unit / mock-verified only. The tests in tests/nosql/signoz.test.ts are fully mock-driven: an in-memory SigNozHttpClient that records every request and returns canned responses is injected via SigNozStoreOptions.client. There is no live SigNoz deployment and no network in the test run. What this proves: push builds the OTLP resourceLogs envelope correctly — resource attributes as { key, value } pairs, and each record's timeUnixNano/severityText/body.stringValue plus attributes mapped to the right AnyValue kind (intValue for 200, boolValue for true). query posts /api/v4/queryrange with start/end/step merged over the builder payload. labels/streams route to the log-fields/services endpoints. Lifecycle: idempotent connect(), getClient() returning the injected client, and ConnectionError before connect(). Error handling: client failures wrapped in DatabaseError. What this does not prove: live execution against a real SigNoz deployment. Request/response shapes are verified against SigNoz's documented OTLP/HTTP and query-range contract, but end-to-end execution over the wire has not been exercised here. Related reading All data stores — the full catalogue, grouped by purpose Database types — where this sits among the 22 categories