Skip to content

Commit 062f9fd

Browse files
wowalyclaude
wowaly
and
claude
authored
docs: add UModel-OpenTelemetry semantic convention mapping (discussion draft) (#14)
Add otel-mapping.md as proposed in Issue #7, PR 1 of the RFC sequence. This is a community discussion draft prepared by CAICT, mapping UModel concepts (EntitySet, Entity, Relation, Field constraints) to OpenTelemetry equivalents (Instrumentation Scope, Resource Attributes, Span Link, Semantic Conventions). The document is intentionally lightweight — a concept bridge, not a schema design. An extended version with worked examples is available for workshop discussions. Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
1 parent 711c797 commit 062f9fd

1 file changed

Lines changed: 115 additions & 0 deletions

File tree

‎docs/en/otel-mapping.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# UModel ↔ OpenTelemetry Semantic Convention Mapping
2+
3+
**Community Discussion Draft**
4+
5+
> 本文档由信通院（CAICT）发起，作为 UModel 社区和 OpenTelemetry 社区之间语义约定对齐的讨论起点。后续可由信通院发起主题研讨会，邀请相关社区共同讨论和完善。
6+
7+
---
8+
9+
## Document Status
10+
11+
**This is a discussion draft, not a finalized specification.**
12+
13+
This document was prepared by CAICT (China Academy of Information and Communications Technology) as a strawman proposal to facilitate community conversation. It does not represent an official position of the UModel maintainers, the OpenTelemetry project, or the CNCF.
14+
15+
**Process:**
16+
17+
1. **Community review** — Submitted as a PR to `alibaba/UnifiedModel` at `docs/en/otel-mapping.md` for open discussion (this PR)
18+
2. **Workshop discussion** — CAICT may convene a thematic workshop where domain experts from the OTel and UModel communities review and refine this draft
19+
3. **Revision** — Incorporate feedback; re-submit for final review
20+
4. **Publication** — Publish as a stable reference once consensus is reached
21+
22+
An extended version with worked examples and schema design sketches is available from CAICT upon request, intended as workshop discussion material rather than a prescriptive design.
23+
24+
---
25+
26+
## 1. Purpose
27+
28+
This document proposes a conceptual mapping between UModel's data model and OpenTelemetry's semantic conventions. Its goals are:
29+
30+
- **Onboarding**: Help observability engineers familiar with OTel understand UModel concepts in their own vocabulary.
31+
- **Interop**: Explore how OTel signals (traces, metrics, logs) could map to UModel entities, relations, and datasets.
32+
- **Alignment**: Serve as a reference so that future UModel schema contributions can align with OTel conventions where appropriate.
33+
34+
This is a discussion draft, not an implementation guide.
35+
36+
---
37+
38+
## 2. Architecture Alignment
39+
40+
Both systems separate **model definitions** from **runtime instances**:
41+
42+
| Layer | UModel | OpenTelemetry |
43+
|-------|--------|---------------|
44+
| Definition | EntitySet (declares entity shape in schema YAML) | Semantic Convention Registry (declares attribute schemas in YAML) |
45+
| Definition | EntitySetLink (declares relation semantics) | Span Link / Service Map conventions |
46+
| Definition | DataSet (MetricSet, LogSet, TraceSet) | Instrumentation Scope + Pipeline configuration |
47+
| Runtime | Entity record (domain, type, id, properties) | Resource + Span / LogRecord / Metric data point |
48+
| Runtime | Relation record (source, dest, type) | Span Link / Service Map edge |
49+
| Query | SPL (`.entity`, `.topo`, `.umodel`) | OTLP pipeline → backend query language |
50+
51+
A key observation for discussion: an OTel-instrumented service appears to project naturally to a set of UModel EntitySets, Entities, and Relations. Whether this holds across diverse deployment scenarios is one of the questions this draft aims to test.
52+
53+
---
54+
55+
## 3. Proposed Conceptual Mapping
56+
57+
> Each row is open for discussion. Field names, mapping choices, and boundary cases are expected to evolve through community feedback.
58+
59+
### 3.1 Core Concept Map
60+
61+
| UModel Concept | OpenTelemetry Equivalent | Notes |
62+
|---------------|-------------------------|-------|
63+
| EntitySet | Instrumentation Scope | Both define a typed schema for runtime instances |
64+
| Entity (domain, type, id) | Resource Attributes (`service.namespace`, `service.name`, `service.instance.id`) | The three-part entity key maps naturally to OTel's service identity model |
65+
| Relation (topo edge) | Span Link / Service Map Edge | Cross-service relationships captured as topology edges |
66+
| Field constraints | Semantic Convention attributes | Schema-level field definitions correspond to OTel attribute conventions |
67+
68+
### 3.2 Signal Mapping (Initial Proposal)
69+
70+
| OTel Signal | UModel Construct | Notes |
71+
|-------------|-----------------|-------|
72+
| Trace (Span) | TraceSet + Entity (`operation`) + Relations | Spans can project to operation entities; parent-child → `parent_of` relations; CLIENT-SERVER pairs → `calls` relations |
73+
| Metric | MetricSet + DataLink to Entity | Metrics linked to producing entity via DataLink; keyed by `service.name` or trace context |
74+
| Log | LogSet + DataLink to Entity | Logs linked to entity via DataLink; trace context enables correlation |
75+
| Span Event | EventSet | Events as first-class UModel objects when warranted |
76+
77+
### 3.3 Resource Attributes → Entity Identity
78+
79+
UModel entities are identified by a three-part convention (domain, entity type, entity id). The following OTel resource attributes are proposed as the natural mapping:
80+
81+
| OTel Resource Attribute | Role in UModel Entity Identity | Notes |
82+
|--------------------------|-------------------------------|-------|
83+
| `service.namespace` | Domain | Organizational boundary (e.g., "production", "staging") |
84+
| `service.name` | Entity type | The kind of thing this entity is (e.g., a microservice name) |
85+
| `service.instance.id` | Entity id | Unique instance identifier |
86+
| `service.version` | Entity property | Service version as an entity property |
87+
| `deployment.environment` | Entity property | Environment context, may also inform domain |
88+
89+
---
90+
91+
## 4. Open Questions
92+
93+
The following are proposed as discussion topics for the UModel community and for any future thematic workshops convened by CAICT:
94+
95+
1. **Span → Entity volume**: An active microservice generates millions of spans per hour. Should every span become an Entity, or only sampled/ERROR spans?
96+
2. **Agent-specific signals**: UModel targets "agent-era observability," but current OTel semantic conventions don't yet cover LLM/Agent spans (work is ongoing in the OTel LLM SIG). How should agent concepts (model name, token count, tool calls) map to UModel constructs?
97+
3. **Metrics temporality**: OTel supports cumulative and delta temporality. UModel MetricSet currently has no temporality field — should one be added?
98+
4. **Baggage propagation**: OTel Baggage carries cross-cutting context (`tenant_id`, `user_id`). These could map to entity properties, but the pattern needs discussion.
99+
5. **Resource Schema URL**: OTel v1.26+ `schema_url` maps naturally to UModel's `schema.version` — should this correspondence be formalized?
100+
101+
---
102+
103+
## 5. Relationship to Other UModel Schemas
104+
105+
This document does not propose new schema kinds. It explores a convention for using existing schema kinds (EntitySet, TraceSet, MetricSet, LogSet, EventSet, EntitySetLink, DataLink) to model OTel-instrumented systems.
106+
107+
---
108+
109+
## 6. Acknowledgments
110+
111+
This discussion draft was prepared by CAICT as part of the "Semantic Conventions for Agentic Workloads" initiative.
112+
113+
An extended version of this document with worked examples and illustrative schema sketches is available for workshop discussions. Please contact the authors or comment on this PR if interested.
114+
115+
**Feedback welcome.** Please comment on this PR or join the upcoming workshop discussion.

0 commit comments

Comments
 (0)