hashicorp / hashicorp/consul

docs: Improve guidance around the need to setup telemetry

Open
#10,326 1 comment 0 reactions 0 assignees View on GitHub
theme/reliability theme/telemetry type/docs
Dominant language
Go
Stars
30.1k
Forks
4.6k
Avg merge
1d 18h
Merged PRs (30d)
39

Description

While reviewing incidents recently we realised that our [telemetry docs](https://www.consul.io/docs/agent/telemetry) don't specifically call out the importance of monitoring servers in production. We have somewhat assumed this is standard practice however we've come across several users who have Consul in production with no easy access to it's telemetry.

We do have a much more useful and prescriptive [Production Readiness guide](https://learn.hashicorp.com/tutorials/consul/production-checklist) on learn which includes setting up monitoring with a few different backends but this isn't linked anywhere from our main docs site.

Easy things to consider:
- [ ] Add a paragraph to the telemetry page to spell out that it's necessary to monitor Consul metrics in production
- [ ] Add links to https://learn.hashicorp.com/tutorials/consul/production-checklist from there for more detailed information
- [ ] Add links to the above guide in other places in docs which might be where people go to try and work out how to run Consul in Production:
- [Bootstrapping a Datacenter](https://www.consul.io/docs/install/bootstrapping)
- [Server Performance](https://www.consul.io/docs/install/performance)
- The Getting Started overview: it already links to the guides on learn in general but we could call out the production readiness one specifically.

Contributor guide

Open the contributing guide

Research direction

Start with the telemetry documentation and compare it with the Production Readiness guide linked in the issue. Add production-monitoring guidance and links from the telemetry page, Bootstrapping a Datacenter, Server Performance, and the Getting Started overview; done means each relevant page points readers to the detailed production checklist.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.