Skip to content

fix: reconcile pillar env var naming — rename MELLEA_LOG_* to MELLEA_LOGS_* #1055

@ajbozarth

Description

@ajbozarth

Problem

Mellea's three telemetry pillars use inconsistent env var prefixes:

Pillar Prefix OTel partner var
Metrics MELLEA_METRICS_* (plural) OTEL_EXPORTER_OTLP_METRICS_ENDPOINT (plural) ✅
Logging MELLEA_LOG_* (singular) OTEL_EXPORTER_OTLP_LOGS_ENDPOINT (plural) ❌
Tracing MELLEA_TRACES_* (plural, landing via #444) OTEL_EXPORTER_OTLP_TRACES_ENDPOINT (plural) ✅

The logging pillar is the outlier. It originally shipped plural in PR #635 (MELLEA_LOGS_OTLP) per the #460 plan comment, and was renamed to singular in PR #907.

With tracing landing plural in #444 (matching OTEL_EXPORTER_OTLP_TRACES_ENDPOINT), the logging pillar becomes the only one out of step with both its own OTel partner var and its sibling Mellea pillars.

Proposed fix

Rename the logging env vars to plural, matching metrics and tracing:

Current (singular) Proposed (plural)
MELLEA_LOG_ENABLED MELLEA_LOGS_ENABLED
MELLEA_LOG_OTLP MELLEA_LOGS_OTLP
MELLEA_LOG_CONSOLE MELLEA_LOGS_CONSOLE
MELLEA_LOG_FILE MELLEA_LOGS_FILE
MELLEA_LOG_FILE_MAX_BYTES MELLEA_LOGS_FILE_MAX_BYTES
MELLEA_LOG_FILE_BACKUP_COUNT MELLEA_LOGS_FILE_BACKUP_COUNT
MELLEA_LOG_JSON MELLEA_LOGS_JSON
MELLEA_LOG_LEVEL MELLEA_LOGS_LEVEL
MELLEA_LOG_WEBHOOK MELLEA_LOGS_WEBHOOK

Keep the old MELLEA_LOG_* names working with a deprecation warning for one release, matching the pattern used for metrics renames and for the tracing rename in #444.

Rationale

  1. OTel alignment — all three signal-specific endpoint env vars defined by the OTel OTLP Exporter spec are plural (OTEL_EXPORTER_OTLP_{METRICS,LOGS,TRACES}_ENDPOINT). Mellea's own vars should match their OTel partner vars.
  2. Internal consistencyMELLEA_METRICS_* and (post-Epic: Enhanced distributed tracing #444) MELLEA_TRACES_* are both plural. Leaving logging singular creates a three-way inconsistency users have to memorize.
  3. Low cost — one-release deprecation window keeps the change non-breaking. The rename itself is mechanical.

Alternatives considered

  • Leave as-is. The inconsistency persists; users configuring all three pillars have to remember a different convention for logging. Low user-facing cost, zero implementation cost.
  • Rename metrics and tracing to singular instead. Would match logging but break alignment with the OTel standard partner vars (all plural) and require more rename churn across two pillars instead of one.

Acceptance criteria

  • All MELLEA_LOG_* env vars renamed to MELLEA_LOGS_* in mellea/core/utils.py and anywhere else they're read.
  • Old names emit deprecation warnings and continue to work for one release.
  • Docs updated.
  • Tests updated.

Related

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions