otel.md

📝 Minimal Professional Microservice Logging Standard (OTel-Compliant)

Field	Type	Required	Notes / Spec	Spec Link
timestamp	string (ISO 8601)	✅	Log event time	Logs Data Model
severity_text	string	✅	Human-readable severity (e.g., INFO, ERROR)	Logs Data Model
severity_number	int	✅	Numeric severity	Logs Data Model
trace_id	string	✅ if trace available	Correlates log to trace	Trace Context in Logs
span_id	string	✅ if trace available	Correlates log to span	Trace Context in Logs
body	string or object	✅	Official log message field in OTel	Logs Data Model
attributes	map	✅	Container for semantic attributes	Logs Data Model

🔹 Recommended Semantic Attributes (dot notation)

Attribute	Type	Required / Optional	Notes	Spec Link
service.name	string	✅	Name of the microservice	Resource Semantic Conventions
service.version	string	✅	Microservice version	Resource Semantic Conventions
deployment.environment	string	✅	e.g., production, staging	Resource Semantic Conventions
http.method	string	Conditional	HTTP request method	HTTP Semantic Conventions
http.status_code	int	Conditional	HTTP response status	HTTP Semantic Conventions
db.system	string	Conditional	e.g., postgres, mysql	DB Semantic Conventions
db.statement	string	Conditional	SQL query or statement	DB Semantic Conventions
messaging.system	string	Conditional	e.g., kafka, rabbitmq	Messaging Semantic Conventions
messaging.destination	string	Conditional	Topic / queue name	Messaging Semantic Conventions

🔹 Optional / Log-Specific Attributes

Attribute	Notes	Spec Link
log.record.uid	Unique ID for log record	Logs Semantic Conventions
log.record.original	Original log string if transformed	Logs Semantic Conventions
log.file.name	File name of source	Logs Semantic Conventions
log.iostream	stdin / stdout / stderr	Logs Semantic Conventions

⚠️ Naming Rules & Notes

Trace/Span IDs → use underscore (trace_id, span_id) — official spec.

Message content → use body for OTel compliance. Can map to message for developer familiarity.

Semantic attributes → use dot notation (service.name, http.method).

Logs may include structured payloads in body (JSON object), not just strings.

✅ Example Log JSON (OTel Compliant)

{
  "timestamp": "2026-02-19T10:00:00.000Z",
  "severity_text": "ERROR",
  "severity_number": 17,
  "body": "User login failed",
  "trace_id": "5b8efff798038103d269b633813fc60c",
  "span_id": "eee19b7ec3c1b174",
  "attributes": {
    "service.name": "auth-service",
    "service.version": "1.0.3",
    "deployment.environment": "production",
    "http.method": "POST",
    "http.status_code": 401,
    "user.email": "john.doe@example.com",
    "auth.attempts": 3
  }
}

This gives you a full, spec-citable logging contract. It answers your body vs message and trace_id vs trace.id questions with direct links to the official OpenTelemetry docs.