OTLP Virtual Database

The OTLP_VIRTUAL_DATABASE layer holds the databases that OpenTelemetry-instrumented services call, reconstructed from the callers’ spans. A database appears here when a CLIENT span of an OpenTelemetry Service names it, through db.system.name and the peer address or peer name the span carries; the database itself reports nothing, so every figure describes it as its clients see it. The layer is kept apart from the agent path’s Virtual Database layer because its metrics come from a different engine under their own otlp_* names.

In Horizon’s sidebar this layer is named OTLP Virtual Database (grouped under OpenTelemetry, with the OTLP Service layer). Each database is listed as one of the Databases. It is a virtual-target layer with a single scope: only the Service scope is enabled; there is no instance or endpoint scope, no topology, and no traces or logs tabs. The database does appear as a node on the OpenTelemetry Service layer’s topology, where the edges into it carry the calls.

This page is the operator reference for the bundled OTLP Virtual Database dashboard.

The widgets and metrics below are read from the bundled OTLP_VIRTUAL_DATABASE template; if an operator has published a customized OTLP_VIRTUAL_DATABASE template to OAP, the live dashboard reflects that copy instead. See Layer Dashboard Templates.

Service list

The landing page lists every database with three sortable columns, sorted by Access RPM by default:

  • Access RPM — queries per minute, counted from the callers’ spans (otlp_database_access_cpm).

  • Latency — average duration of those spans in ms (otlp_database_access_resp_time).

  • Error Rate — percent of them that failed: status ERROR, or an HTTP status of 400 or above (100 - otlp_database_access_sla/100).

Service dashboard

  • Access Traffic — queries per minute (otlp_database_access_cpm).

  • Avg Response Time — mean latency of the callers’ spans in ms (otlp_database_access_resp_time).

  • Success Rate — percent of the callers’ spans that did not fail, as in the list (otlp_database_access_sla/100).

  • Slow Statements — the top 20 slowest statements the shipped otlp-slow-sql rule recorded against this database, in ms, worst-first (top_n(top_n_database_statement, 20, des)). Each row is one statement execution; click a row to copy the statement, or use the trace icon at the row head to open its trace from the OTLP trace store, over this page. The rule records a statement at 200 ms or more by default; the threshold is in the rule file.

Databases without an address

An embedded or in-process database reports no address in its spans. The OAP names such a database after its system and namespace, h2/mem-db, so it still appears in this list with its access metrics and slow statements, next to the address-named databases.

Requirements

The dashboard is a pure consumer of what OAP reports. To populate it, OAP needs the OTLP trace receiver with the trace-analyzer module’s shipped rule file, and client spans that name the database: db.system.name or db.system with service.peer.name, peer.service, or server.address and server.port. A span that names the system but no address or peer is filed under a database named after its system and namespace, such as h2/mem-db; see Databases without an address. For the upstream setup see the OpenTelemetry trace analysis documentation.