feat: add optional prometheus metrics endpoint.

[pantierra]

Adds opt-in Prometheus metrics support via prometheus-fastapi-instrumentator, controlled by ENABLE_METRICS / enable_metrics. Metrics remain disabled by default and the dependency is available through the metrics extra.

[codecov]

Codecov Report

❌ Patch coverage is 84.21053% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.42%. Comparing base (fec33b6) to head (0f1c068).
⚠️ Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
src/stac_auth_proxy/metrics.py	83.33%	4 Missing and 1 partial ⚠️
src/stac_auth_proxy/app.py	87.50%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #186      +/-   ##
==========================================
- Coverage   89.49%   89.42%   -0.08%     
==========================================
  Files          29       30       +1     
  Lines        1276     1314      +38     
  Branches      171      176       +5     
==========================================
+ Hits         1142     1175      +33     
- Misses         92       96       +4     
- Partials       42       43       +1     

Flag	Coverage Δ
unittests	89.42% <84.21%> (-0.08%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[alukach]

Left some thoughts.

As stated in developmentseed/eoapi-k8s#541 (comment), I'm generally in favor of this idea.

Before we merge this, we will want to ensure that the PR includes an update to our documentation. At the very least, we should update the config docs. We may also want to include something long-form within /tips.

One thing that stands out to me is how I don't really understand how this works in various deployment scenarios. Based on the fact that we're not configuring any datastore with this plugin, I assume these metrics are held within memory. So how would that work in a multi-node environment? Or what about a serverless environment where an AWS Lambda may or may not be warmed?

[pantierra]

Can you have a look again, please? If you agree with this approach (enabled by default, dependency added in main bulk) I am happy to add the documentation.

[alukach]

@pantierra sorry for the back-and-forth.

• serving metrics from /_mgmt/metrics: 👍
• having /_mgmt/metrics in default public_endpoints: 👍

However, I do still think this should be an optional dependency

[pantierra]

I wasn't sure how you want to do the conditional. Inspired from stac-fastapi-elasticsearch-opensearch I made it to add the metrics endpoint if the dependency extra metrics is installed. And we somehow have to deal with adding/removing it from the public_endpoints depending on the conditional.

I gave it a try. Feel free to add over this branch if you prefer to change it. Or just let me know, I am fine to change it to you think is best.

[pantierra]

One thing that stands out to me is how I don't really understand how this works in various deployment scenarios. Based on the fact that we're not configuring any datastore with this plugin, I assume these metrics are held within memory. So how would that work in a multi-node environment? Or what about a serverless environment where an AWS Lambda may or may not be warmed?

Yes, metrics are held in memory. In a multi-node setup, Prometheus scrapes each pod separately with possible aggregation when querying them. Serverless is trickier as the metrics need to be pushed. Afaik there are several approaches, but i don't have experience with any.

[pantierra]

Based on input developmentseed/eoAPI#193 (comment), adjusted the structure of the metrics to be more STACish.

[claude]

Claude finished @pantierra's task in 4m 16s —— View job

---

Reviewing PR #186

• Gather context (diff, changed files)
• Review for correctness bugs, security issues, best practices
• Apply ponytail-review lens for over-engineering
• Post final review

---

✅ No blocking issues — safe to merge.

Reviewed the diff of src/stac_auth_proxy/{app.py,metrics.py,config.py}, Dockerfile, pyproject.toml, uv.lock, and the tests against origin/main. The extras-gated approach (METRICS_AVAILABLE set via try/except ImportError at import time, endpoint toggled via presence in public_endpoints) is sound, matches what was agreed upon in the review thread, and is covered by tests for both the "extra installed" and "extra absent" paths.

Two non-blocking observations worth being aware of (not asking for changes, since both reflect the tradeoffs already discussed and approved in this thread):

• src/stac_auth_proxy/app.py:90-96 — enabling metrics is coupled to /_mgmt/metrics being in public_endpoints. If an operator instead moves the path to private_endpoints (e.g. to require auth/scope for scraping) rather than removing it outright, metrics silently stop being instrumented at all rather than becoming an authenticated endpoint. Worth a doc callout if this comes up in support.
• src/stac_auth_proxy/metrics.py:8-33 — the OPERATIONS route-shape table (^/collections/[^/]+/items/[^/]+$, etc.) duplicates the path shapes already encoded in config.py's private_endpoints. Low risk today, but the two tables can drift if STAC route shapes change in only one place.

Simplify (ponytail)

• src/stac_auth_proxy/metrics.py:8-33 — OPERATIONS regex table re-encodes route shapes that already exist in config.py's private_endpoints/public_endpoints → could derive operation labels from those existing patterns instead of maintaining a second parallel table.

---

💰 Estimated review cost: $1.09 · 4m16s · 27 turns