* 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>
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
QueryContextchanges must cover HTTP, gRPC, MySQL, and PostgreSQL entry points. - Internal frontend gRPC listeners set
Channel::Internalin 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
QueryContextstate; 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>