What is observability ontology?

Your AIOps tool keeps saying “scale up.” The real cause was a weekly backup job eating all the disk I/O.

This isn’t a model quality problem. The model just doesn’t know your system.

Two things are broken before you even get to the AI layer.

First: LLMs have no knowledge of your private topology. They don’t know Service A calls Service B over internal network. They don’t know about that Wednesday 2 AM backup. That context doesn’t exist in their training data, and RAG over generic docs doesn’t fix it.

Second: your signals are isolated by design. Metrics in one store, logs in another, traces in a third. PromQL, LogQL, TraceQL. When something breaks, you’re manually stitching context across consoles. The model sees the same fragmented picture you do.

Observability ontology is the missing layer. Model your system as a graph of entities (services, pods, databases) with data bound to each entity and relationships explicitly defined. When an alert fires, the system finds the entity, pulls all associated context, and traverses the dependency graph. Every hop in the reasoning chain is explicit and auditable. The on-call engineer at 3 AM can verify the logic, not just trust it.

The concept is 2,000 years old. Aristotle’s Metaphysics asked: what entities exist, how are they classified, and how do they relate? The same three questions apply to your Kubernetes cluster.

We’re working on this at GreptimeDB. The first piece we shipped is a Semantic Layer that preserves OTLP metadata (instrument kind, unit, temporality) that normally gets discarded at ingestion. Agents can now read 𝘨𝘳𝘦𝘱𝘵𝘪𝘮𝘦.𝘴𝘦𝘮𝘢𝘯𝘵𝘪𝘤.* table options instead of guessing from column names. Small change, concrete payoff.

Four-card visual explainer in the thread. Docs: http://docs.greptime.com/user-guide/concepts/semantic-layer…

And the follow-up RFC: https://github.com/GreptimeTeam/greptimedb/pull/8605…

Table Semantic Layer (Experimental) | GreptimeDB Documentation

Source: https://docs.greptime.com/user-guide/concepts/semantic-layer/ warning

The semantic layer is experimental and may change in future releases. Tables without semantic metadata keep working unchanged; the layer is optional and additive.

The semantic layer attaches a thin layer of metadata to each table so machine consumers — LLM agents, alert and dashboard builders,MCP servers, ETL pipelines — can align a table with the observability concept it represents, without guessing from column names.

Why it exists​

GreptimeDB ingests OTLP metrics, traces, and logs, plus Prometheus remote write, InfluxDB, OpenTSDB, Loki, and Elasticsearch. Each protocol carries rich metadata on the wire — instrument kind, temporality, unit, semantic-conventions version — and most of it is dropped once rows land in a table:

• An OTLP traces table looks like any other wide table; signal type and source must be guessed from naming.
• A metric’s unit (s,By) is discarded by the row encoders and is unrecoverable from the data.
• OTLP aggregation temporality (cumulativevsdelta) is invisible in the metric name.
• A Prometheuscountertyped from a\_totalsuffix is aguess, not a declaration — but the table never flags that.

The metadata to remove the guess already exists at ingest time. The semantic layer preserves it instead of throwing it away. An alert generator can then choose betweenrate\(\)and absolute thresholds; a dashboard builder can pick a visualization by signal type; an agent can read a structured catalog instead of inferring from column names.

How it works​

The layer reuses existing SQL surfaces — no new protocol, no new DDL keyword. It has three mechanisms:

1. greptime\.semantic\.\*table options— table-level identity and lineage, carried inside the existingtable\_optionsslot (the same slot that holdsttl,table\_data\_model, etc.).
2. ColumnCOMMENT— standard SQL, for column-level supplements.
3. information\_schema\.table\_semantics— a queryable view, the discovery entry point. It returns one row per table that carries at least onegreptime\.semantic\.\*option.

Vocabulary​

All keys are flat strings under thegreptime\.semantic\.prefix; all values are strings. The vocabulary is deliberately small — a key earns its place only when it records something a consumer cannot cheaply recover from the schema, the columns, or the metric naming conventions it already understands. Keys whose value is already in the metric name (a Prometheus\_totalsuffix), is a constant, or merely restates a column are intentionally omitted.

The whitelist is closed: an unrecognized key under the prefix (such asgreptime\.semantic\.future\.key) or an out-of-domain value is rejected.

Common keys (all signals)​

KeyDescriptionExample valuesgreptime\.semantic\.signal\_typeThe telemetry signal the table represents.metric/trace/log/event/unknown``greptime\.semantic\.sourceThe ingestion ecosystem that wrote the data.opentelemetry/prometheus/influxdb/opentsdb/loki/elasticsearch/custom/mixed/unknown``greptime\.semantic\.pipelineThe internal ingestion data model. The signal-agnostic successor totable\_data\_model.greptime\_trace\_v1### Trace keys​

KeyDescriptionExample valuesgreptime\.semantic\.trace\.conventionsThe semantic-conventions version the rows conform to, typically an OTel schema URL.https://opentelemetry\.io/schemas/1\.27\.0/mixed/unknown### Metric keys​

KeyDescriptionExample valuesgreptime\.semantic\.metric\.typeThe instrument kind.counter/gauge/histogram/summary/updown\_counter/gauge\_histogram/info/stateset/mixed/unknown``greptime\.semantic\.metric\.unitThe unit inUCUMnotation. Discarded by the row encoders, so unrecoverable once ingested.s/By/\{request\}``greptime\.semantic\.metric\.temporalityAggregation temporality (OTLP only). Invisible in the metric name.cumulative/delta/mixed/unknown``greptime\.semantic\.metric\.metadata\_qualityHow the metric type was obtained — how much you can trustmetric\.type.declared(the protocol stated it) /inferred(guessed from a name suffix) /unknown``greptime\.semantic\.metric\.original\_nameThe pre-translation OpenTelemetry name, recorded when the table name was Prometheus-ised.http\.server\.duration``metadata\_qualityis the load-bearing field for confidence-aware tooling: aninferredcounter should be re-checked before betting onrate\(\)-style semantics.

unknownandmixedare shared sentinels.unknownmeans the value could not be determined when the option was stamped;mixedmeans a single-valued key saw conflicting values over the table’s lifetime — for a long-lived table that received rows from more than one source. Treat any single-valued semantic key as best-effort, not strong evidence.

Automatic stamping on ingestion​

The auto-create paths stamp identity (signal\_type+source) on every supported protocol. OTLP metrics additionally carry the full metric vocabulary, because the OTLP wire format declares type/unit/temporality and then discards them; OTLP traces carry the pipeline and conventions.

Ingestion pathsignal\_type``sourceAdditional keysOTLP metricsmetric``opentelemetry``metric\.type,metric\.unit,metric\.temporality,metric\.metadata\_quality=declared,metric\.original\_nameOTLP tracestrace``opentelemetry``pipeline=greptime\_trace\_v1,trace\.conventionsOTLP logslog``opentelemetry—Prometheus remote writemetric``prometheusidentity only (type/unit live in the metric name)InfluxDB line protocolmetric``influxdbidentity onlyOpenTSDBmetric``opentsdbidentity onlyLokilog``lokiidentity onlyElasticsearchlog``elasticsearchidentity onlySemantic options are stamped at table creation. There is no update path yet: promotingmetadata\_qualityfrominferredtodeclared, or revisingtrace\.conventionson later writes, is deferred.

Manual tagging with DDL​

You can set the same options yourself inCREATE TABLE \.\.\. WITH \(\.\.\.\). Only whitelisted keys with a valid value are accepted:

CREATE TABLE my_metrics (  ts TIMESTAMP TIME INDEX,  val DOUBLE) WITH (  'greptime.semantic.signal_type' = 'metric',  'greptime.semantic.source' = 'custom',  'greptime.semantic.metric.type' = 'counter',  'greptime.semantic.metric.unit' = 'By');

The options appear inSHOW CREATE TABLEoutput and in thetable\_semanticsview.

A consumer’s first query on connect lists every semantic-tagged table:

SELECT table_schema, table_name, signal_type, source, pipeline, metadata_quality, semantic_optionsFROM information_schema.table_semanticsORDER BY table_name;

signal\_type,source,pipeline, andmetadata\_qualityare promoted to dedicated columns; the remaining signal-specific keys are folded into thesemantic\_optionsJSON string (with thegreptime\.semantic\.prefix stripped). See theTABLE\_SEMANTICSreference for the full schema and more examples.

TheGreptimeDB MCP Serverreads this view so AI assistants can understand your tables without you spelling out what each one means.