Better telemetry docs

[ryanuber]

What

Adds details for telemetry data, including logs, tracing, and metrics. This change attempts to give good coverage of current metrics, without including any details which are subject to change, such as the tags and labels applied to each metric. This is intended to provide a basic inventory of metrics and high-level descriptions of what each measurement means.

Why

Multiple users have asked for this, and this follows the same general pattern for documenting metrics as taken by other products such as Nomad or Consul.

Screenshots

---

Merge Checklist

If items do not apply to your changes, add (N/A) and mark them as complete.

Pull Request

• One or more labels describe the type of change (e.g. clarification) and associated product (e.g. tfc).
• Description links to related pull requests or issues, if any.

Content

• Redirects have been added for moved, renamed, or deleted pages. This requires a separate PR in the terraform-website repository redirects.next.js file.
• API documentation and the API Changelog have been updated.
• Links to related content where appropriate (e.g., API endpoints, permissions, etc.).
• Pages with related content are updated and link to this content when appropriate.
• Sidebar navigation files have been updated for added, deleted, reordered, or renamed pages.
• New pages have metadata (page name and description) at the top.
• New images are 2048 px wide. They have HashiCorp standard annotation color (#F92672) and format (rectangle with rounded corners), blurred sensitive details (e.g. credentials, usernames, user icons), and descriptive alt text in the markdown for accessibility.
• New code blocks have the correct syntax and line breaks to eliminate horizontal scroll bars.
• UI elements (button names, page names, etc.) are bolded.
• The Vercel website preview successfully deployed.

Reviews

• I or someone else reviewed the content for technical accuracy.
• I or someone else reviewed the content for typos, punctuation, spelling, and grammar.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated
terraform-docs-agents	✅ Ready (Inspect)	Visit Preview	💬 Add your feedback	Jan 31, 2023 at 10:19PM (UTC)

[claire-tfc]

This is an amazing amount of data to get documented! 🎉 Thank you for all the time this must have taken.

[zisom-hc]

In total, all of this new verbosity is great; thank you Ryan for the time put into consolidating all this information. Here are my edits/suggestions:

[zisom-hc]

Providing a list of all available trace would still provide a benefit, as it would allow people to be able to verify how many there are/they should expect, and whether they are successfully ingesting all the ones that are associated to the particular operations they've executed.

[ryanuber]

This is the type of documentation that would go stale very easily, which is why I opted to not include it. I think the maintenance burden ends up outweighing the utility here. It's similar to not documenting every log line - I believe it is overly verbose, and the user should be able to get context on any given trace frame from looking at the frame itself. Metrics are a bit different, as users are likely to build monitors around them and depend on them to some extent, and there is not a good cross-platform way of ensuring they provide accurate and understandable context without additional documentation.

[zisom-hc]

That's fair, granted i do want to note that this will make it difficult for the support team to provide guidance to customers when they ask questions about what traces we emit, and how many. this will essentially leave the support engineer to have to manually uncover this information through the source code, or through internal documentation that is hopefully kept up to date. Given the amount of effort that's been put into this new iteration of documentation, and your reasonings for not including it, i'm okay with foregoing this requirement of the Feature Request, and awaiting feedback from Home Depot, and other customers, as to whether this is desired.

[zisom-hc]

Comments about the example commands

[ryanuber]

Thanks so much for the thorough read, @zisom-hc ! I applied your suggestions.

[zisom-hc]

new edits LGTM, 🚢

[natalie-todd]

I added a couple of tiny spelling nits.

This context/documentation is extremely helpful for the tfc-agent telemetry project. Thank you!

[judithpatudith]

Thank you!