feat(prometheus): add per-team litellm_team_members_metric gauge

[yassin-berriai]

Relevant issues

Linear ticket

Resolves LIT-3082

Pre-Submission checklist

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

• I have added meaningful tests
• My PR passes all CI/CD checks (e.g., lint, format, unit tests)
• 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

Screenshots / Proof of Fix

Live proxy with callbacks: ["prometheus"] against a real Postgres. The metric is scraped straight off /metrics. Master key auth elided as $KEY, base URL is the proxy

Before the change, on the base branch, adding a member emits no such metric at all

$ curl -s -X POST "$B/team/member_add" -H "$H" \
    -d '{"team_id":"'"$TID"'","member":{"role":"user","user_id":"grace"}}'
$ curl -sL -H "$H" "$B/metrics" | grep -i team_members
(metric ABSENT on base - feature not present)

After the change, the gauge appears and tracks the team's current member count up and down. Sequence below starts from a team that already has default_user_id (admin) plus alice, bob, carol

=== current ===
litellm_team_members_metric{team="8128cae0-...",team_alias="Acme Production"} 4.0

=== member_add dave  ->  5 ===
litellm_team_members_metric{team="8128cae0-...",team_alias="Acme Production"} 5.0

=== member_delete alice  ->  4 ===
litellm_team_members_metric{team="8128cae0-...",team_alias="Acme Production"} 4.0

=== member_delete bob  ->  3 ===
litellm_team_members_metric{team="8128cae0-...",team_alias="Acme Production"} 3.0

=== second team, bulk_member_add eve+frank (delegates to member_add) ===
litellm_team_members_metric{team="8128cae0-...",team_alias="Acme Production"} 3.0
litellm_team_members_metric{team="7483bf0b-...",team_alias="Other Team"} 3.0

The HELP/TYPE lines confirm the registration

# HELP litellm_team_members_metric Number of members in a team
# TYPE litellm_team_members_metric gauge

Type

🆕 New Feature

Changes

Adds a per-team Prometheus gauge litellm_team_members_metric, labelled by team (team id) and team_alias, that reflects the number of members in a team. It is emitted from /team/member_add and /team/member_delete (and /team/bulk_member_add, which delegates to member add), so the count rises on each add and falls on each delete as the ticket asks

The gauge is set to the team's authoritative member count after the membership write rather than incremented or decremented by a delta. That keeps it equal to the real current membership, so it never drifts negative and self-corrects on the first change after a proxy restart, which a delta-since-startup counter cannot do. The delete-path emission sits immediately after the authoritative team-table update so the gauge stays consistent with the persisted state even if a later cleanup step raises

Emission goes through a small _emit_team_members_metric seam that fetches the PrometheusLogger from litellm.callbacks and no-ops when Prometheus is not enabled, so this is zero-cost for proxies that have not registered the callback and a metric failure can never break a team add or delete

Tests cover the gauge being set to the member count for several counts, that re-emitting overwrites with the authoritative value rather than accumulating, the team_alias=None fallback to an empty label, per-team label isolation, and the seam's registered/unregistered/raising paths

[yassin-berriai]

@greptileai

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[greptile-apps]

Greptile Summary

This PR adds a per-team Prometheus gauge for team member counts. The main changes are:

• Registers litellm_team_members_metric with team and team_alias labels
• Sets the gauge from the current members_with_roles count after member add/delete operations
• Adds tests for gauge values, label isolation, empty alias handling, and the endpoint emission seam

Confidence Score: 5/5

The change is narrowly scoped to Prometheus metric emission for team membership updates and includes focused coverage for the new gauge behavior.

No correctness issues were identified in the changed metric registration, emission seam, or endpoint update paths, and the tests cover the important label and count semantics.

T-Rex Logs

What T-Rex did

• Observed the pre-change team-members metric state, which showed HTTP/1.1 200 OK and no metric samples.
• Applied member operations and observed metric updates: after member_add, team-a=1.0; after bulk add, team-a=3.0; after delete, team-a=2.0; team-b with empty alias remains at 2.0 and isolated; final registry samples are present.
• Verified final registry samples are present, confirming the end state.

_{Ran code and verified through T-Rex}

_{Reviews (1): Last reviewed commit: "feat(prometheus): add per-team litellm_t..." | Re-trigger Greptile}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[greptile-apps]

Greptile Summary

This PR adds a Prometheus metric for per-team member counts. The main changes are:

• Registers litellm_team_members_metric with team and team_alias labels
• Sets the gauge from the current members_with_roles count after member add and delete operations
• Adds tests for gauge values, label isolation, callback behavior, and metric failure handling

Confidence Score: 5/5

The change appears safe to merge.

The implementation is narrowly scoped, covered by targeted tests, and no correctness or security issues were identified.

T-Rex Logs

What T-Rex did

• Ran T-Rex to verify the team-members metric; observed base HEAD had no litellm_team_members_metric and, after the run, the metric appeared as a gauge named Number of members in a team with samples team='team-a', team_alias='Alpha Alias' at 1.0/3.0/2.0 and team='team-b', team_alias='Beta Alias' at 2.0 after bulk add.
• Ran T-Rex to validate the metric seam safety; observed before-run flags showed has__emit_team_members_metric=False and has_set_team_members_metric=False, and after-run results included noop_when_unregistered=ok, raises_suppressed=ok calls=1, latest_authoritative_value=2.0, and an exported sample with labels team='team-empty-alias', team_alias=''.

_{Ran code and verified through T-Rex}

_{Reviews (2): Last reviewed commit: "feat(prometheus): add per-team litellm_t..." | Re-trigger Greptile}