Semantic Conventions
All telemetry attributes follow standardized naming conventions.
lakeFS Attributes
Semantic conventions for lakeFS versioning and file access tracking.
Commit-level
| Constant | Value | Description |
|---|---|---|
LAKEFS_COMMIT_SHA | lakefs.commit.sha | Commit SHA hash |
LAKEFS_COMMIT_BRANCH | lakefs.commit.branch | Branch name at commit time |
LAKEFS_COMMIT_TIMESTAMP | lakefs.commit.timestamp | Commit timestamp |
LAKEFS_COMMIT_MESSAGE | lakefs.commit.message | Commit message |
LAKEFS_COMMIT_AUTHOR | lakefs.commit.author | Commit author |
Repository / workstream
| Constant | Value | Description |
|---|---|---|
LAKEFS_REPOSITORY | lakefs.repository | Repository name |
LAKEFS_BRANCH | lakefs.branch | Active branch |
LAKEFS_ENGAGEMENT_ID | lakefs.engagement_id | Engagement identifier |
LAKEFS_WORKSTREAM_ID | lakefs.workstream_id | Workstream identifier |
File-level
| Constant | Value | Description |
|---|---|---|
LAKEFS_FILE_PATH | lakefs.file.path | Object path |
LAKEFS_FILE_SIZE | lakefs.file.size | File size in bytes |
LAKEFS_FILE_MODIFIED | lakefs.file.modified | Last modified timestamp |
LAKEFS_FILE_HASH | lakefs.file.hash | Content hash |
LAKEFS_FILE_CONTENT_TYPE | lakefs.file.content_type | MIME type |
Artifact / operation
| Constant | Value | Description |
|---|---|---|
LAKEFS_ARTIFACT_PREFIX | lakefs.artifact. | Prefix for artifact attributes |
LAKEFS_OPERATION | lakefs.operation | Operation type (read, write, list) |
LAKEFS_ACCESS_TIME | lakefs.access.timestamp | Access timestamp |
Workflow Attributes
Semantic conventions for multi-agent workflow correlation.
Workflow-level
| Constant | Value | Description |
|---|---|---|
WORKFLOW_ID | workflow.id | Unique workflow identifier |
WORKFLOW_NAME | workflow.name | Workflow name |
WORKFLOW_STARTED_AT | workflow.started_at | Start timestamp |
WORKFLOW_COMPLETED_AT | workflow.completed_at | Completion timestamp |
WORKFLOW_STATUS | workflow.status | Current status |
WORKFLOW_AGENT_COUNT | workflow.agent_count | Number of agents |
WORKFLOW_AGENT_CHAIN | workflow.agent_chain | Ordered agent chain |
Agent-level
| Constant | Value | Description |
|---|---|---|
AGENT_WORKFLOW_ID | agent.workflow_id | Parent workflow ID |
AGENT_PARENT_ID | agent.parent_id | Parent agent ID |
AGENT_POSITION_IN_CHAIN | agent.position | Position in execution chain |
Correlation
| Constant | Value | Description |
|---|---|---|
TRACE_ID | trace.id | Distributed trace ID |
PARENT_SPAN_ID | parent.span_id | Parent span ID |
RAG Attributes
Semantic conventions for RAG component versioning and retrieval tracking.
Document versioning
| Constant | Value | Description |
|---|---|---|
RAG_DOCUMENT_ID | rag.document.id | Document identifier |
RAG_DOCUMENT_VERSION | rag.document.version | Document version |
RAG_DOCUMENT_PATH | rag.document.path | Document path |
RAG_DOCUMENT_HASH | rag.document.hash | Content hash |
RAG_DOCUMENT_UPDATED_AT | rag.document.updated_at | Last update timestamp |
Embedding versioning
| Constant | Value | Description |
|---|---|---|
RAG_EMBEDDING_MODEL | rag.embedding.model | Model name |
RAG_EMBEDDING_MODEL_VERSION | rag.embedding.model.version | Model version |
RAG_EMBEDDING_DIMENSIONS | rag.embedding.dimensions | Vector dimensions |
RAG_EMBEDDING_CREATED_AT | rag.embedding.created_at | Creation timestamp |
RAG_EMBEDDING_BATCH_ID | rag.embedding.batch_id | Batch identifier |
Vector index versioning
| Constant | Value | Description |
|---|---|---|
RAG_INDEX_NAME | rag.index.name | Index name |
RAG_INDEX_VERSION | rag.index.version | Index version |
RAG_INDEX_SIZE | rag.index.size | Index size |
RAG_INDEX_UPDATED_AT | rag.index.updated_at | Last update timestamp |
Retrieval provenance
| Constant | Value | Description |
|---|---|---|
RAG_QUERY_TEXT | rag.query.text | Query text |
RAG_QUERY_EMBEDDING_MODEL | rag.query.embedding.model | Query embedding model |
RAG_TOP_K | rag.retrieval.top_k | Top-k parameter |
RAG_SIMILARITY_THRESHOLD | rag.retrieval.similarity_threshold | Similarity threshold |
RAG_RETRIEVED_COUNT | rag.retrieval.count | Number of results retrieved |
Retrieved document tracking
| Constant | Value | Description |
|---|---|---|
RAG_RESULT_DOCUMENT_ID | rag.result.document.id | Result document ID |
RAG_RESULT_SCORE | rag.result.score | Similarity score |
RAG_RESULT_RANK | rag.result.rank | Result rank |
RAG_RESULT_DOCUMENT_VERSION | rag.result.document.version | Result document version |
Version drift detection
| Constant | Value | Description |
|---|---|---|
RAG_VERSION_DRIFT | rag.version.drift | Drift detected flag |
RAG_VERSION_DRIFT_REASON | rag.version.drift.reason | Drift reason |
External Data Attributes
Semantic conventions for external data source versioning and tracking.
API versioning
| Constant | Value | Description |
|---|---|---|
EXTERNAL_API_NAME | external.api.name | API name |
EXTERNAL_API_VERSION | external.api.version | API version |
EXTERNAL_API_ENDPOINT | external.api.endpoint | Endpoint URL |
EXTERNAL_API_METHOD | external.api.method | HTTP method |
EXTERNAL_API_STATUS_CODE | external.api.status_code | Response status code |
Data versioning
| Constant | Value | Description |
|---|---|---|
EXTERNAL_DATA_SOURCE | external.data.source | Data source name |
EXTERNAL_DATA_TIMESTAMP | external.data.timestamp | Data timestamp |
EXTERNAL_DATA_HASH | external.data.hash | Data hash |
EXTERNAL_DATA_SIZE | external.data.size | Data size |
EXTERNAL_DATA_RECORD_COUNT | external.data.record_count | Record count |
ETL job tracking
| Constant | Value | Description |
|---|---|---|
EXTERNAL_ETL_JOB_ID | external.etl.job_id | ETL job ID |
EXTERNAL_ETL_RUN_ID | external.etl.run_id | ETL run ID |
EXTERNAL_ETL_PIPELINE | external.etl.pipeline | Pipeline name |
Database query tracking
| Constant | Value | Description |
|---|---|---|
EXTERNAL_DB_SYSTEM | external.db.system | Database system |
EXTERNAL_DB_NAME | external.db.name | Database name |
EXTERNAL_DB_QUERY | external.db.query | Query string |
EXTERNAL_DB_QUERY_HASH | external.db.query_hash | Query hash |
EXTERNAL_DB_RESULT_COUNT | external.db.result_count | Result count |
Cache tracking
| Constant | Value | Description |
|---|---|---|
EXTERNAL_CACHE_KEY | external.cache.key | Cache key |
EXTERNAL_CACHE_HIT | external.cache.hit | Cache hit flag |
EXTERNAL_CACHE_TTL | external.cache.ttl | TTL in seconds |
Snapshot metadata
| Constant | Value | Description |
|---|---|---|
EXTERNAL_SNAPSHOT_ID | external.snapshot.id | Snapshot identifier |
EXTERNAL_SNAPSHOT_TIMESTAMP | external.snapshot.timestamp | Snapshot timestamp |
EXTERNAL_SNAPSHOT_LOCATION | external.snapshot.location | Storage location |
Validation Attributes
Semantic conventions for prompt-knowledge validation.
Validation status
| Constant | Value | Description |
|---|---|---|
VALIDATION_STATUS | validation.status | Overall validation status |
VALIDATION_MODE | validation.mode | Validation mode |
VALIDATION_LAYER | validation.layer | Validation layer |
Reference tracking
| Constant | Value | Description |
|---|---|---|
VALIDATION_REFERENCE_COUNT | validation.reference.count | Number of references |
VALIDATION_REFERENCE_EXTRACTED | validation.reference.extracted | Extracted references |
VALIDATION_REFERENCE_TYPE | validation.reference.type | Reference type |
Error tracking
| Constant | Value | Description |
|---|---|---|
VALIDATION_ERROR_COUNT | validation.error.count | Error count |
VALIDATION_ERROR_CODE | validation.error.code | Error code |
VALIDATION_ERROR_MESSAGE | validation.error.message | Error message |
VALIDATION_ERROR_REFERENCE | validation.error.reference | Error reference |
VALIDATION_ERROR_SEVERITY | validation.error.severity | Error severity |
Resolution details
| Constant | Value | Description |
|---|---|---|
VALIDATION_RESOLUTION_TIME_MS | validation.resolution.time_ms | Resolution time in ms |
VALIDATION_LAKEFS_COMMIT | validation.lakefs.commit | Source commit SHA |
VALIDATION_LAKEFS_BRANCH | validation.lakefs.branch | Source branch |
Semantic validation
| Constant | Value | Description |
|---|---|---|
VALIDATION_SEMANTIC_ENABLED | validation.semantic.enabled | Semantic check enabled |
VALIDATION_SEMANTIC_MODEL | validation.semantic.model | Model used |
VALIDATION_SEMANTIC_CONFIDENCE | validation.semantic.confidence | Confidence score |
Remediation
| Constant | Value | Description |
|---|---|---|
VALIDATION_REMEDIATION_SUGGESTION | validation.remediation.suggestion | Remediation suggestion |
Usage
Import semantic conventions to use standardized attribute names:
from briefcase.semantic_conventions import lakefs
# Use attributes in spans
span.set_attribute(lakefs.LAKEFS_COMMIT_SHA, commit_sha)
span.set_attribute(lakefs.LAKEFS_FILE_PATH, file_path)
from briefcase.semantic_conventions import rag
# Track RAG retrieval
span.set_attribute(rag.RAG_DOCUMENT_ID, doc_id)
span.set_attribute(rag.RAG_RESULT_SCORE, 0.95)
This ensures consistency across your telemetry data.