Skip to content

chore(Observability): evaluate OTel semantic convention attribute names #249

Description

@jlian

Context

Phase 1 structured logging uses an Azure Monitor-inspired schema (operationName, resultSignature, resultDescription, etc.). The OTel semantic conventions use different attribute names (http.request.method, http.route, http.response.status_code, url.path, error.type).

Currently, Cloudflare's native tracing layer uses OTel conventions for infrastructure spans (D1, R2, fetch), so our application logs complement rather than duplicate those.

What

Evaluate whether to align application log field names with OTel semantic conventions when OTel export is enabled:

  • resultSignature -> http.response.status_code
  • operationName -> split into http.request.method + http.route
  • Add error.type on error paths
  • Add url.path, url.scheme as standard attributes

This could be a logger configuration option (e.g., LOG_FORMAT=otel) or a mapping layer at export time.

Trade-offs

  • Pro: Better correlation between application logs and infrastructure traces in OTel backends.
  • Con: Current naming is more readable for human consumption; may lose clarity.
  • Option: Keep both - human-readable names in properties, OTel names as top-level attributes.

Prerequisites

  • Blocked on OTel export being live (no point renaming if we are reading logs in Cloudflare dashboard).

Acceptance criteria

  • Decision documented in docs/OBSERVABILITY.md.
  • If adopted, all log emit sites use OTel attribute names (or a mapper handles it).

References

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions