Files
greptimedb/src/servers/AGENTS.md
T
shuiyisong ee1fc7782f feat(prometheus): query persisted metric exemplars (#9924)
* feat(prometheus): add exemplar queries and lifecycle coverage

Expose /v1/prometheus/api/v1/query_exemplars with exact time bounds and series selectors. Resolve and authorize source selectors before scanning exemplar storage, enforce query limits and cancellation, preserve exact observation identity, and return warnings for malformed stored rows.

Includes HTTP and authorization tests, pre-created-table and concurrent-DDL coverage, OTLP Arrow ingestion checks, and cross-protocol lifecycle tests across memory, WAL, SST, compaction and reopen. The query-dependent ingestion tests live here so every lower layer builds independently. Add metric-exemplar usage and retention guidance.

Signed-off-by: shuiyisong <xixing.sys@gmail.com>

* fix(exemplar): preserve query labels with source identities

Signed-off-by: shuiyisong <xixing.sys@gmail.com>

* fix(exemplar): floor bounds and add audit hooks

Signed-off-by: shuiyisong <xixing.sys@gmail.com>

* • fix(exemplar): include aggregation parameter selectors

Signed-off-by: shuiyisong <xixing.sys@gmail.com>

* fix(prometheus): avoid v1 exemplar quota stalls

Signed-off-by: shuiyisong <xixing.sys@gmail.com>

* fix: docs

Signed-off-by: shuiyisong <xixing.sys@gmail.com>

* fix: align exemplar query timestamps with Prometheus

Signed-off-by: shuiyisong <xixing.sys@gmail.com>

* chore: remove unnecessory doc

Signed-off-by: shuiyisong <xixing.sys@gmail.com>

---------

Signed-off-by: shuiyisong <xixing.sys@gmail.com>
2026-11-10 08:11:49 +00:00

3.5 KiB

servers — Agent & Contributor Guide

Navigation map for src/servers. Repo-wide invariants: .agents/architecture-invariants.md.

servers owns network listeners and protocol translation. Database behavior is provided through handler traits, mostly implemented by frontend.

Module map

Area Path Entry point
Lifecycle src/servers/src/server.rs Shared Server trait
Handler boundary src/servers/src/query_handler.rs, src/servers/src/query_handler/ Protocol-independent handler traits
gRPC / Flight src/servers/src/grpc.rs, src/servers/src/grpc/ gRPC services, auth, cancellation, builders
HTTP src/servers/src/http.rs, src/servers/src/http/ Routes, middleware, protocol endpoints, output formats
SQL protocols src/servers/src/mysql.rs, src/servers/src/mysql/, src/servers/src/postgres.rs, src/servers/src/postgres/ MySQL/PostgreSQL servers and type conversion
Observability protocols src/servers/src/prom_remote_write/, src/servers/src/prometheus.rs, src/servers/src/otlp/, src/servers/src/otel_arrow.rs Prometheus and OpenTelemetry conversion
Exemplars src/servers/src/exemplar/, src/servers/src/exemplar.rs, src/servers/src/http/prom_store/exemplar.rs Shared row contract, millisecond query API, completion-aware metric/exemplar writes
Resources / TLS src/servers/src/request_memory_limiter.rs, src/servers/src/tls.rs, src/servers/src/addrs.rs Memory admission, TLS, listener addresses

Change coupling

  • Handler trait changes require matching frontend and mock implementations.
  • gRPC wire changes start in greptime-proto; update builders and handlers here after bumping it.
  • Auth or QueryContext changes must cover HTTP, gRPC, MySQL, and PostgreSQL entry points.
  • Internal frontend gRPC listeners set Channel::Internal in server-owned request extensions. Handlers preserve it through query execution and metering; client flow metadata does not grant an internal channel.
  • Finite requests split by wire handlers (Prometheus batching and OpenTSDB summary/details) admit all rows before dispatch. Admission is process-local QueryContext state; never accept it from headers or serialized contexts.
  • New protocols or externally visible routes also require frontend service and configuration wiring.

Testing

cargo nextest run -p servers

Keep protocol translation here and permissions/database behavior in frontend. Async table batching returns storage-completion futures with its early acknowledgements. Keep completion reporting independent of the caller's lifetime. Remote-write v2 keeps decoder reservations and per-request progress through queued writes; error responses drain those writes before reporting partial counts. Logical-table physical flushes retain partition columns in Arrow RPC payloads and pass all region writes to the operator write dispatcher together; the dispatcher owns peer resolution and retries. See batcher/logical_table/region_write.rs.

prom_remote_write/decode.rs and benches/prom_decode.rs resolve benches/write_request.pb.data using CARGO_MANIFEST_DIR at run time (std::env::var, not env!). cargo nextest run and cargo bench set it; direct test/benchmark-binary execution requires setting it to the crate directory. Run this example from the repository root:

CARGO_MANIFEST_DIR="$PWD/src/servers" ./target/debug/deps/<test_or_bench_binary>