Feat - Add organization into the metrics metadata for org_id & org_alias

[J-Byron]

Relevant issues

Resolves #24251

Pre-Submission checklist

Please complete all items before asking a LiteLLM maintainer to review your PR

• [ x] I have Added testing in the tests/test_litellm/ directory, Adding at least 1 test is a hard requirement - see details
• My PR passes all unit tests on make test-unit
• My PR's scope is as isolated as possible, it only solves 1 specific problem
• I have requested a Greptile review by commenting @greptileai and received a Confidence Score of at least 4/5 before requesting a maintainer review

Delays in PR merge?

If you're seeing a delay in your PR being merged, ping the LiteLLM Team on Slack (#pr-review).

CI (LiteLLM team)

CI status guideline:

• 50-55 passing tests: main is stable with minor issues.
• 45-49 passing tests: acceptable but needs attention
• <= 40 passing tests: unstable; be careful with your merges and assess the risk.

• Branch creation CI run
  Link:

• CI run for the last commit
  Link:

• Merge / cherry-pick CI run
  Links:

Type

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
litellm	Ready	Preview, Comment	Mar 30, 2026 4:55am

[CLAassistant]

All committers have signed the CLA.

[J-Byron]

@greptileai

[codspeed-hq]

Merging this PR will not alter performance

✅ 16 untouched benchmarks

---

_{Comparing J-Byron:feat/prometheus-org-request-labels (9eb14a2) with main (5812053)}

[greptile-apps]

Greptile Summary

This PR adds org_id and org_alias dimensions to LiteLLM's Prometheus metrics for requests associated with an organization. The implementation spans the full stack: fetching organization_alias from the DB via an extended SQL join in PrismaClient.get_data, storing it on LiteLLM_VerificationTokenView (and therefore UserAPIKeyAuth), propagating it through StandardLoggingUserAPIKeyMetadata in the pre-call utils, and finally injecting org_id/org_alias labels into 11 existing metrics via the new _org_label_metrics frozenset in PrometheusMetricLabels.get_labels().

Key observations:

• The DB query change correctly LEFT JOINs LiteLLM_OrganizationTable to fetch organization_alias — the data source is sound.
• prometheus.py correctly uses .get() for user_api_key_org_alias (safe for payloads not built through the pre-call utils path).
• The _org_label_metrics frozenset dynamically adds the new labels to metric registration at startup — this is a backwards-incompatible change for existing Prometheus deployments (cardinality of these 11 metrics changes, breaking existing time-series and dashboards), and unlike the existing prometheus_emit_stream_label pattern, it is not gated behind a feature flag.
• In proxy_server.py, user_api_key_org_alias is set unconditionally across all three updated endpoint handlers, while user_api_key_org_id is guarded by a not-None check — a minor inconsistency in the request metadata structure.

Confidence Score: 3/5

Caution advised — the org label injection unconditionally changes the cardinality of 11 existing Prometheus metrics, which is a breaking change for any user already consuming these metrics.

The functional implementation is sound (DB query, model field, metadata propagation, and safe .get() reads are all correct). However, the unconditional addition of two new label dimensions to 11 existing, widely-used Prometheus metrics without a feature flag violates the project's backwards-compatibility policy and will silently break existing dashboards and alerting rules for current users on upgrade. Gating the new labels behind a flag (similar to prometheus_emit_stream_label) would resolve this concern and raise the score to 4-5.

litellm/types/integrations/prometheus.py — the _org_label_metrics frozenset approach needs a feature flag before this can be considered safe to merge for existing deployments.

Important Files Changed

Filename	Overview
litellm/integrations/prometheus.py	Adds org_id and org_alias to UserAPIKeyLabelValues construction in both success and failure emission paths; uses .get() safely for metadata reads
litellm/proxy/_types.py	Adds organization_alias: Optional[str] = None to LiteLLM_VerificationTokenView, making it available on UserAPIKeyAuth instances via inheritance
litellm/proxy/litellm_pre_call_utils.py	Adds user_api_key_org_alias to StandardLoggingUserAPIKeyMetadata construction via user_api_key_dict.organization_alias
litellm/proxy/proxy_server.py	Adds user_api_key_org_alias unconditionally to request metadata in chat_completion, completion, and embeddings handlers — inconsistent with conditional org_id pattern
litellm/proxy/utils.py	Extends the verification token SQL query to fetch organization_alias from LiteLLM_OrganizationTable, enabling DB-backed population of the new field
litellm/types/integrations/prometheus.py	Introduces _org_label_metrics frozenset that unconditionally appends org_id/org_alias to 11 existing metrics via get_labels(), a backwards-incompatible label schema change without a feature flag
litellm/types/utils.py	Adds user_api_key_org_alias: Optional[str] to StandardLoggingUserAPIKeyMetadata TypedDict, correctly extending the schema
tests/test_litellm/integrations/test_prometheus_user_team_metrics.py	New test verifies org labels appear in per-request metrics and are absent from non-org metrics; also checks deduplication with custom_prometheus_metadata_labels
tests/test_litellm/integrations/test_prometheus_client_ip_user_agent.py	Existing test updated to include the two new TypedDict keys (org_id/org_alias as None) in the metadata fixture — necessary schema update, no coverage regression

Sequence Diagram

sequenceDiagram
    participant Client
    participant ProxyServer
    participant PreCallUtils
    participant DB
    participant Prometheus

    Client->>ProxyServer: POST /chat/completions
    ProxyServer->>DB: get_data(token) with org alias JOIN
    DB-->>ProxyServer: UserAPIKeyAuth (organization_alias populated)
    ProxyServer->>ProxyServer: set org_alias in request metadata

    ProxyServer->>PreCallUtils: get_sanitized_user_information_from_key()
    PreCallUtils->>PreCallUtils: build StandardLoggingUserAPIKeyMetadata (includes user_api_key_org_alias)
    PreCallUtils-->>ProxyServer: standard_logging_payload with org metadata

    ProxyServer->>Prometheus: async_log_success_event(payload)
    Prometheus->>Prometheus: read org_alias via metadata.get()
    Prometheus->>Prometheus: build UserAPIKeyLabelValues with org fields
    Prometheus->>Prometheus: get_labels() appends org_id and org_alias for metrics in _org_label_metrics frozenset
    Prometheus->>Prometheus: emit litellm_requests_metric with org labels

    ProxyServer->>Prometheus: async_log_failure_event(user_api_key_dict)
    Prometheus->>Prometheus: read org fields from user_api_key_dict directly
    Prometheus->>Prometheus: emit litellm_proxy_failed_requests_metric with org labels

Loading

Comments Outside Diff (1)

1. litellm/proxy/proxy_server.py, line 7015 (link)

   Inconsistent conditional guard for org_alias vs org_id

   user_api_key_org_id is only written to data["metadata"] when it is not None (guarded by both hasattr and a not-None check), but user_api_key_org_alias is written unconditionally — even when organization_alias is None. This means the metadata dict will sometimes contain the key "user_api_key_org_alias" with value None while the key "user_api_key_org_id" is entirely absent. The same pattern is repeated in all three handlers (chat_completion, completion, embeddings).

   This is inconsistent and can be surprising for any custom callback that reads from data["metadata"] expecting the same presence/absence semantics for both fields. Consider aligning the guard:

   The same fix should be applied at the corresponding lines in the completion (~line 7190) and embeddings (~line 7433) handlers as well.

_{Reviews (15): Last reviewed commit: "fix: write org_alias to metadata uncondi..." | Re-trigger Greptile}

[greptile-apps]

org_alias is always hardcoded to None

user_api_key_org_alias is unconditionally set to None here. UserAPIKeyAuth (and its parents LiteLLM_VerificationTokenView / LiteLLM_VerificationToken) do not have an org_alias field — the org alias is only extracted transiently from JWT tokens in handle_jwt.py and is used solely to resolve an org_id via a DB lookup, but never stored in UserAPIKeyAuth.

As a result, the org_alias Prometheus label will always be None for every metric emission, making the feature effectively a no-op. To fix this:

1. Add an org_alias: Optional[str] field to LiteLLM_VerificationTokenView (or UserAPIKeyAuth).
2. Populate it during JWT auth in handle_jwt.py where org_alias is resolved (around line 1151).
3. Then use user_api_key_dict.org_alias here instead of None.

[greptile-apps]

Breaking change to existing Prometheus metric label schemas

Adding org_id and org_alias to all of these existing metric label lists (across litellm_llm_api_latency_metric, litellm_requests_metric, litellm_spend_metric, litellm_total_tokens_metric, etc.) is a backwards-incompatible change for anyone already running LiteLLM with Prometheus.

In Prometheus, a metric's identity is defined by its name and its complete set of label names. When label names change, the old time-series become orphaned and any existing dashboards or alerting rules that query these metrics by label set will break silently. This violates the pattern of avoiding backwards-incompatible changes without user-controlled flags (e.g. a litellm.prometheus_emit_org_labels feature flag, similar to how litellm.prometheus_emit_stream_label controls the stream label).

Consider gating the new labels behind a feature flag, similar to the existing prometheus_emit_stream_label pattern visible in prometheus.py.

[greptile-apps]

Direct key access for new field risks KeyError

user_api_key_org_alias is accessed with ["user_api_key_org_alias"] (direct dict access) rather than .get("user_api_key_org_alias"). Any StandardLoggingPayload whose metadata was not built through litellm_pre_call_utils.get_sanitized_user_information_from_key (e.g. pass-through endpoints, cost-tracking callback) will not have this key in the dict, raising a KeyError that silently swallows the entire Prometheus metric recording.

Using .get() is the safer approach here and matches how other optional fields are read elsewhere in this class:

Suggested change

	user_api_key_org_id = standard_logging_payload["metadata"]["user_api_key_org_id"]
	user_api_key_org_alias = standard_logging_payload["metadata"][
	"user_api_key_org_alias"
	]
	user_api_key_org_id = standard_logging_payload["metadata"].get("user_api_key_org_id")
	user_api_key_org_alias = standard_logging_payload["metadata"].get(
	"user_api_key_org_alias"
	)

[J-Byron]

@greptileai

[J-Byron]

@greptileai

[J-Byron]

@shivamrawat1

Screenshot of the /metrics endpoint showing org_id and org_alias now appearing as labels on per-request Prometheus metrics (litellm_proxy_total_requests_metric_total). Previously these labels weren't there — now when a key is associated with an org, both fields show up alongside the existing team/team_alias labels.

Gated behind prometheus_emit_org_labels: true in litellm_settings since adding new labels to existing metrics creates new time series, which would be a breaking change for anyone with existing Prometheus/Grafana setups.

[krrish-berri-2]

gated behind a prometheus_emit_org_labels feature flag (default False).

@J-Byron why is this feature flagged?

cc: @shivamrawat1 was this part of the user request?

Ideally we avoid more user flags - as it requires more building - e.g. how does a user on the ui enable this?

[shivamrawat1]

@J-Byron @krrish-berri-2 is right. They should be added by default in the metrics. We already have advanced settings if more granular control of labels is needed. https://docs.litellm.ai/docs/proxy/prometheus#configuring-metrics-and-labels https://docs.litellm.ai/docs/proxy/prometheus#configuring-metrics-and-labels please fix to follow the same pattern

[J-Byron]

@J-Byron why is this feature flagged?

@krrish-berri-2 @shivamrawat1
Greptile is giving me a 3/5 review for not handling backwards compatibility. I am now following the same default pattern as team_alias / team_id but it keeps flagging the approach. I was only able to get a 4/5 by adding a feature flag.

Greptile: The functional implementation is sound (DB query, model field, metadata propagation, and safe .get() reads are all correct). However, the unconditional addition of two new label dimensions to 11 existing, widely-used Prometheus metrics without a feature flag violates the project's backwards-compatibility policy and will silently break existing dashboards and alerting rules for current users on upgrade. Gating the new labels behind a flag (similar to prometheus_emit_stream_label) would resolve this concern and raise the score to 4-5.