feat: Add comprehensive Prometheus metrics support

[rossigee]

Summary

This PR adds comprehensive Prometheus metrics support to Vaultwarden, providing observability into application performance, database health, authentication patterns, and business metrics.

Key Features

• Optional metrics endpoint at /metrics (disabled by default)
• Token-based authentication with support for plain text and Argon2 hashed tokens
• Comprehensive metric categories: HTTP, database, authentication, business, and system metrics
• Secure by default: Feature must be explicitly enabled and compiled with --features enable_metrics
• Production-ready: Path normalization prevents metric explosion, proper error handling

Metrics Categories

• HTTP Metrics: Request rates, response times, status codes by endpoint
• Database Metrics: Connection pool utilization, query performance
• Authentication Metrics: Login attempts, session counts by method and status
• Business Metrics: User counts, vault items by type, organization data
• System Metrics: Uptime, build information, version details

Security Considerations

• Disabled by default - requires explicit ENABLE_METRICS=true
• Token authentication prevents unauthorized access
• Path normalization prevents high cardinality issues
• Network isolation recommended for production

Documentation

• Complete configuration guide in METRICS.md
• Comprehensive monitoring setup in MONITORING.md
• Prometheus/Grafana examples and alerting rules
• Security best practices and troubleshooting

Test Plan

• Metrics compilation with feature flag
• Authentication (no token, valid token, invalid token)
• Metric format validation (Prometheus format)
• All metric categories populated correctly
• Path normalization working
• Docker build with metrics feature
• Security token hashing (Argon2)

Breaking Changes

None - this is an optional feature that's disabled by default.

Files Added/Modified

• New: src/api/metrics.rs - Metrics endpoint implementation
• New: METRICS.md - Configuration and usage guide
• New: MONITORING.md - Complete monitoring setup guide
• New: examples/metrics-config.env - Configuration examples
• New: scripts/test-metrics.sh - Testing script
• Modified: Cargo.toml - Added optional prometheus dependency
• Modified: README.md - Added metrics feature documentation
• Modified: docker/Dockerfile.debian - Support for extra features in build

[tessus]

You sort of beat me to it. I was thinking of adding OTel: also metrics, but mostly traces. Even though the vw service is not highly distributed (maybe a db backend on a different machine), traces are still useful just to verify where exactly the time is spent. Also helps a lot with debugging. I despise logs unless they are audit logs. ;-)

Great job adding the Prometheus metrics!

[deajan]

Is there any chance to see this comming ?

[rossigee]

Is there any chance to see this comming ?

Doesn't look like it. If there's no sign of interest from the maintainer within a reasonable time, I'll close the PR.

[BlackDex]

Maybe some patients would be nice. The maintainers do have a life outside of this project. And they maintain this in there spare free time.

I also do not see closing it will help anything. And keeping it open should be that hard either.

[rossigee]

@BlackDex - i appreciate that maintainers have lives outside their project etc. Contributors do too. I am both to various projects. I was not trying to be impatient or rude. It's just the way I work.

There is another side to the maintainer/contributor coin that people often don't consider. Sometimes a contributor has many, many PRs outstanding against many, many third-party projects. Some are against actively maintained projects, others not so actively maintained. I'm getting too old now to be maintaining an ever-increasing backlog of PRs against other people's projects in my spare time that just aren't likely to get merged, so every couple of weekends or so I check up on the older PRs, maybe chase one or two. If it's still outstanding, and none of the maintainers hasn't acknowledged, commented on, reviewed or even given it a 'thumbs up' emoji or any kind, I think it's safe to assume they don't consider whatever I'm contributing to be very important to them. So it gets closed.

If I do end up closing this PR, it's not a problem. I'm more than happy if others want to fork my fork and create their own PR to persist it, and maybe they'll have better luck pushing the maintainers on it. The contribution is still there for anyone who wants it, I just ain't sitting on PRs forever as they go stale.

In this case, I knew before I did the work that it was unlikely that this would get merged. Because, before I did it I looked for prior work and found this...

#3634

You said...

My view of this is to not add it, but point users to the other project.

So, really, I just pushed this as a PR on the off chance that minds might have changed, or that this patch was a little more acceptable than mpatterson's. And to give it a public airing, so that others that do want this feature can have it.

I haven't closed it yet.

[tessus]

I believe this PR has a better chance to get merged than the one you mentioned, since it provides token access and thus does not make the access to the endpoint available to the public.

IMO securing a /metrics endpoint via the web/proxy server is a no-brainer and takes a few seconds, but I guess it is understandable why maintainers are reluctant to add code that provides public access to metrics. But since this is out of the way now, the chances might go up. ;-)

[deajan]

Indeed, usually prometheus metrics are secured by firewalls / proxies so that's pretty standard.

I still hope this gets into vaultwarden, it's a highly useful feature.

Whenever maintainers have time, no hurry.

[BlackDex]

I'm looking at this again, and bit better, but still shifting through it, not testing it out.
But i see a lot of code not really in line with the rest of how Vaultwarden is coded.

Also, not to be rude or anything, but it kinda looks like AI (Vibe coding) was done here (like some comments about production code).
I see stuff like #![allow(dead_code, unused_imports)] which is bad, just remove that and fix the code.

There are places where the err!() or err_code!() macro's should be used instead of typing it manually.

I see unit tests which add no useful tests, they just test basic stuff like normalized_path and if something is a uuid or other weird stuff.

Besides all that, the documentation is something we would like to be on the Wiki instead of in de code-base.

So, there are a lot of items i think which need to be adjusted before this can be merged, I just do not have the time currently to have a better look at this my self and comment on all specific items in the PR.

[rossigee]

Thanks @BlackDex for the review and feedback. Sincerely appreciated.

Yes, it's an AI vibe-coded patch. I don't have enough Rust experience to code this one myself, nor experience with VaultWarden's coding practices etc, so I appreciate you pointing out the bits that will need further attention.

I've marked the patch as draft and will try to make the necessary fixes as time permits, which isn't much these days! However, if it's a feature that a more experienced Rust/VW developer would like to see included, please feel free to take it and run with it.

So, in summary the remaining actions (identified so far) seem to be:

• Fix up error handling to match other Vaultwarden code.
• Remove unnecessary comments from patch
• Make vibe-coded unit tests actually useful.
• Move the documentation to the wiki (might need some help there)
• Further testing, review and feedback

That doesn't sound too difficult.

[rossigee]

Move the documentation to the wiki (might need some help there)

How can I go about this ?

[rossigee]

Prometheus-Metrics.md

[deajan]

Read the documentation. Pretty clear, although a bit repetitive for some configuration variables.
I'll be happy to test this as soon as it lands in beta builds. Thank you for your work.