search

grafana / tempo

Grafana Tempo is a high volume, minimal dependency distributed tracing backend.
https://grafana.com/oss/tempo/
GNU Affero General Public License v3.0
3.9k stars 508 forks source link

[DOC] Address issues found by doc validator #1513

Closed knylander-grafana closed 2 years ago

knylander-grafana commented 2 years ago

Jack posted a list in PR#1512 of issues that need to be fixed in the Tempo documentation:

Where should this link go to? 

$ docker run -v "$(pwd)/docs/tempo/website:/docs/tempo/website" jdbgrafana/doc-validator:latest ./docs/tempo/website | grep "The link"
ERROR: docs/tempo/website/grafana-agent/service-graphs.md: The link "../../server_side_metrics/service_graphs#grafana" is invalid. Ensure the link is a http or https URL, an anchor starting with # or a relative link in the Hugo format (e.g. '{{< relref "path-to.md" >}}' or '{{< relref "path to page" >}}')

There are additional docs validation errors that might be suitable for an Issue:

docker run -v "$(pwd)/docs/tempo/website:/docs/tempo/website" jdbgrafana/doc-validator:latest ./docs/tempo/website | grep -v "The link"
ERROR: docs/tempo/website/api_docs/_index.md: The first heading "Tempo's API" does not match the title "API documentation" in the file docs/tempo/website/api_docs/_index.md

ERROR: docs/tempo/website/configuration/azure.md: The first heading "Azure blob storage permissions and management" does not match the title "Azure permissions and management" in the file docs/tempo/website/configuration/azure.md

ERROR: docs/tempo/website/getting-started/_index.md: The first heading "Getting started with Tempo" does not match the title "Getting started" in the file docs/tempo/website/getting-started/_index.md

ERROR: docs/tempo/website/getting-started/example-demo-app.md: The first heading "Running the Tempo backend" does not match the title "Example setups" in the file docs/tempo/website/getting-started/example-demo-app.md

ERROR: docs/tempo/website/getting-started/instrumentation.md: The first heading "References to use when instrumenting your applications" does not match the title "Instrumentation" in the file docs/tempo/website/getting-started/instrumentation.md

ERROR: docs/tempo/website/grafana-agent/automatic-logging.md: The first heading "Automatic logging: Trace discovery through logs" does not match the title "Automatic logging" in the file docs/tempo/website/grafana-agent/automatic-logging.md

ERROR: docs/tempo/website/grafana-agent/span-metrics.md: The first heading "Generating metrics from spans" does not match the title "Span metrics" in the file docs/tempo/website/grafana-agent/span-metrics.md

ERROR: docs/tempo/website/metrics-generator/span_metrics.md: The first heading "Generating metrics from spans" does not match the title "Span metrics" in the file docs/tempo/website/metrics-generator/span_metrics.md

ERROR: docs/tempo/website/operations/ingester_pvcs.md: The first heading "Ingester persistent volume operations" does not match the title "Ingester PVCs" in the file docs/tempo/website/operations/ingester_pvcs.md

ERROR: docs/tempo/website/operations/monitoring.md: The first heading "Monitoring Tempo" does not match the title "Monitoring" in the file docs/tempo/website/operations/monitoring.md

ERROR: docs/tempo/website/operations/polling.md: The first heading "Polling" does not match the title "Polling and monitoring" in the file docs/tempo/website/operations/polling.md

ERROR: docs/tempo/website/operations/serverless_aws.md: The first heading "AWS Lambda for serverless backend search" does not match the title "Backend search - serverless AWS setup" in the file docs/tempo/website/operations/serverless_aws.md

ERROR: docs/tempo/website/operations/serverless_gcp.md: The first heading "Google Cloud Run for serverless backend search" does not match the title "Backend search - serverless GCP setup" in the file docs/tempo/website/operations/serverless_gcp.md

ERROR: docs/tempo/website/release-notes/v1-2.md: The first heading "Version 1.2 release notes" does not match the title "V1.2" in the file docs/tempo/website/release-notes/v1-2.md

ERROR: docs/tempo/website/release-notes/v1-3.md: The first heading "Version 1.3 release notes" does not match the title "V1.3" in the file docs/tempo/website/release-notes/v1-3.md

ERROR: docs/tempo/website/release-notes/v1-4.md: The first heading "Version 1.4 release notes" does not match the title "V1.4" in the file docs/tempo/website/release-notes/v1-4.md

ERROR: docs/tempo/website/troubleshooting/max-trace-limit-reached.md: The first heading "Distributors refusing spans" does not match the title "Distributor refusing spans" in the file docs/tempo/website/troubleshooting/max-trace-limit-reached.md

ERROR: docs/tempo/website/troubleshooting/too-many-jobs-in-queue.md: The first heading "Error message ‘Too many jobs in the queue’" does not match the title "Too many jobs in the queue" in the file docs/tempo/website/troubleshooting/too-many-jobs-in-queue.md

ERROR: docs/tempo/website/troubleshooting/unable-to-see-trace.md: The first heading "Unable to find traces in Tempo" does not match the title "Unable to Find Traces" in the file docs/tempo/website/troubleshooting/unable-to-see-trace.md
Checklist

[na] Tests updated
[na] Documentation added
[na] CHANGELOG.md updated - the order of entries should be [CHANGE], [FEATURE], [ENHANCEMENT], [BUGFIX]
[jdbaldry](https://github.com/jdbaldry) added 5 commits [3 hours ago](https://github.com/grafana/tempo/pull/1512#commits-pushed-3bb10a6)
@jdbaldry
[Replace manual table of contents with automatic one](https://github.com/grafana/tempo/pull/1512/commits/3bb10a6711ffe7860b282c140c8b3c0e666bffd5) 
[3bb10a6](https://github.com/grafana/tempo/pull/1512/commits/3bb10a6711ffe7860b282c140c8b3c0e666bffd5)
@jdbaldry
[Remove anchor for memberlist that does not exist](https://github.com/grafana/tempo/pull/1512/commits/f670fc12b90a381c9271bb63191b85f685ad1f29) 
[f670fc1](https://github.com/grafana/tempo/pull/1512/commits/f670fc12b90a381c9271bb63191b85f685ad1f29)
@jdbaldry
[Add missing heading to Pushing spans with HTTP page](https://github.com/grafana/tempo/pull/1512/commits/7280dc1eed1e8ce1e02ca522aaca2501b75feb21) 
[7280dc1](https://github.com/grafana/tempo/pull/1512/commits/7280dc1eed1e8ce1e02ca522aaca2501b75feb21)
@jdbaldry
[Fix link to Pushing spans with HTTP page](https://github.com/grafana/tempo/pull/1512/commits/bc6976b31a0c61562bfab8ebf37ff1c9c5170b42) 
[bc6976b](https://github.com/grafana/tempo/pull/1512/commits/bc6976b31a0c61562bfab8ebf37ff1c9c5170b42)
@jdbaldry
[Fix all other links](https://github.com/grafana/tempo/pull/1512/commits/838919633c8965ccdef1f2b854d1e02fe8ba928e) 
[8389196](https://github.com/grafana/tempo/pull/1512/commits/838919633c8965ccdef1f2b854d1e02fe8ba928e)
@[jdbaldry](https://github.com/jdbaldry) jdbaldry requested review from [knylander-grafana](https://github.com/knylander-grafana), [KMiller-Grafana](https://github.com/KMiller-Grafana), [joe-elliott](https://github.com/joe-elliott), [annanay25](https://github.com/annanay25), [mdisibio](https://github.com/mdisibio), [dgzlopes](https://github.com/dgzlopes), [mapno](https://github.com/mapno), [kvrhdn](https://github.com/kvrhdn) and [zalegrala](https://github.com/zalegrala) as [code owners](https://github.com/grafana/tempo/blob/d744ba20bc2a432d1da22acdb6ad358ce660f3f4/CODEOWNERS#L2) [2 hours ago](https://github.com/grafana/tempo/pull/1512#event-6874953376)
@[CLAassistant](https://github.com/CLAassistant)
CLAassistant commented [2 hours ago](https://github.com/grafana/tempo/pull/1512#issuecomment-1165665111) • 
CLA assistant check
All committers have signed the CLA.

[knylander-grafana](https://github.com/knylander-grafana)
knylander-grafana approved these changes [1 hour ago](https://github.com/grafana/tempo/pull/1512#pullrequestreview-1018673023)
Member
[knylander-grafana](https://github.com/knylander-grafana) left a comment
Changes look good. Thank you for updating the relrefs.

@jdbaldry
Member
Author
[jdbaldry](https://github.com/jdbaldry) commented [37 minutes ago](https://github.com/grafana/tempo/pull/1512#issuecomment-1165715013)
I'm having trouble signing the CLA, the version box is blank when I follow the link.

@jdbaldry
Member
Author
[jdbaldry](https://github.com/jdbaldry) commented [26 minutes ago](https://github.com/grafana/tempo/pull/1512#issuecomment-1165724260)
Error
There is no CLA to sign for grafana/tempo
(upstream request timeout)

:(

@knylander-grafana
Member
[knylander-grafana](https://github.com/knylander-grafana) commented [7 minutes ago](https://github.com/grafana/tempo/pull/1512#issuecomment-1165739913)
CLA assistant check Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our [Contributor License Agreement](https://cla-assistant.io/grafana/tempo?pullRequest=1512) before we can accept your contribution.You have signed the CLA already but the status is still pending? Let us [recheck](https://cla-assistant.io/check/grafana/tempo?pullRequest=1512) it.

CLA appears to be no working properly. The link doesn't resolve to an actionable page.

@jdbaldry
Member
Author
[jdbaldry](https://github.com/jdbaldry) commented [5 minutes ago](https://github.com/grafana/tempo/pull/1512#issuecomment-1165741546)
Worked now

Merge state
Add more commits by pushing to the jdb/2022-06-fix-broken-links branch on grafana/tempo.

@knylander-grafana
Fix non relref links to prevent them from breaking (#1512)
* Replace manual table of contents with automatic one

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Remove anchor for memberlist that does not exist

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Add missing heading to Pushing spans with HTTP page

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Fix link to Pushing spans with HTTP page

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Fix all other links

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

@knylander-grafana

Leave a comment
No file chosen
Attach files by dragging & dropping, selecting or pasting them.
Remember, contributions to this repository should follow its [contributing guidelines](https://github.com/grafana/tempo/blob/d744ba20bc2a432d1da22acdb6ad358ce660f3f4/CONTRIBUTING.md) and [code of conduct](https://github.com/grafana/tempo/blob/d744ba20bc2a432d1da22acdb6ad358ce660f3f4/CODE_OF_CONDUCT.md).
 ProTip! Add [.patch](https://github.com/grafana/tempo/pull/1512.patch) or [.diff](https://github.com/grafana/tempo/pull/1512.diff) to the end of URLs for Git’s plaintext views.
Reviewers
@[knylander-grafana](https://github.com/knylander-grafana)
knylander-grafana
@[KMiller-Grafana](https://github.com/KMiller-Grafana)
KMiller-Grafana
@[joe-elliott](https://github.com/joe-elliott)
joe-elliott
@[annanay25](https://github.com/annanay25)
annanay25
@[mdisibio](https://github.com/mdisibio)
mdisibio
@[dgzlopes](https://github.com/dgzlopes)
dgzlopes
@[mapno](https://github.com/mapno)
mapno
@[kvrhdn](https://github.com/kvrhdn)
kvrhdn
@zalegrala

There are additional docs validation errors that might be suitable for an Issue:

docker run -v "$(pwd)/docs/tempo/website:/docs/tempo/website" jdbgrafana/doc-validator:latest ./docs/tempo/website | grep -v "The link"
ERROR: docs/tempo/website/api_docs/_index.md: The first heading "Tempo's API" does not match the title "API documentation" in the file docs/tempo/website/api_docs/_index.md

ERROR: docs/tempo/website/configuration/azure.md: The first heading "Azure blob storage permissions and management" does not match the title "Azure permissions and management" in the file docs/tempo/website/configuration/azure.md

ERROR: docs/tempo/website/getting-started/_index.md: The first heading "Getting started with Tempo" does not match the title "Getting started" in the file docs/tempo/website/getting-started/_index.md

ERROR: docs/tempo/website/getting-started/example-demo-app.md: The first heading "Running the Tempo backend" does not match the title "Example setups" in the file docs/tempo/website/getting-started/example-demo-app.md

ERROR: docs/tempo/website/getting-started/instrumentation.md: The first heading "References to use when instrumenting your applications" does not match the title "Instrumentation" in the file docs/tempo/website/getting-started/instrumentation.md

ERROR: docs/tempo/website/grafana-agent/automatic-logging.md: The first heading "Automatic logging: Trace discovery through logs" does not match the title "Automatic logging" in the file docs/tempo/website/grafana-agent/automatic-logging.md

ERROR: docs/tempo/website/grafana-agent/span-metrics.md: The first heading "Generating metrics from spans" does not match the title "Span metrics" in the file docs/tempo/website/grafana-agent/span-metrics.md

ERROR: docs/tempo/website/metrics-generator/span_metrics.md: The first heading "Generating metrics from spans" does not match the title "Span metrics" in the file docs/tempo/website/metrics-generator/span_metrics.md

ERROR: docs/tempo/website/operations/ingester_pvcs.md: The first heading "Ingester persistent volume operations" does not match the title "Ingester PVCs" in the file docs/tempo/website/operations/ingester_pvcs.md

ERROR: docs/tempo/website/operations/monitoring.md: The first heading "Monitoring Tempo" does not match the title "Monitoring" in the file docs/tempo/website/operations/monitoring.md

ERROR: docs/tempo/website/operations/polling.md: The first heading "Polling" does not match the title "Polling and monitoring" in the file docs/tempo/website/operations/polling.md

ERROR: docs/tempo/website/operations/serverless_aws.md: The first heading "AWS Lambda for serverless backend search" does not match the title "Backend search - serverless AWS setup" in the file docs/tempo/website/operations/serverless_aws.md

ERROR: docs/tempo/website/operations/serverless_gcp.md: The first heading "Google Cloud Run for serverless backend search" does not match the title "Backend search - serverless GCP setup" in the file docs/tempo/website/operations/serverless_gcp.md

ERROR: docs/tempo/website/release-notes/v1-2.md: The first heading "Version 1.2 release notes" does not match the title "V1.2" in the file docs/tempo/website/release-notes/v1-2.md

ERROR: docs/tempo/website/release-notes/v1-3.md: The first heading "Version 1.3 release notes" does not match the title "V1.3" in the file docs/tempo/website/release-notes/v1-3.md

ERROR: docs/tempo/website/release-notes/v1-4.md: The first heading "Version 1.4 release notes" does not match the title "V1.4" in the file docs/tempo/website/release-notes/v1-4.md

ERROR: docs/tempo/website/troubleshooting/max-trace-limit-reached.md: The first heading "Distributors refusing spans" does not match the title "Distributor refusing spans" in the file docs/tempo/website/troubleshooting/max-trace-limit-reached.md

ERROR: docs/tempo/website/troubleshooting/too-many-jobs-in-queue.md: The first heading "Error message ‘Too many jobs in the queue’" does not match the title "Too many jobs in the queue" in the file docs/tempo/website/troubleshooting/too-many-jobs-in-queue.md

ERROR: docs/tempo/website/troubleshooting/unable-to-see-trace.md: The first heading "Unable to find traces in Tempo" does not match the title "Unable to Find Traces" in the file docs/tempo/website/troubleshooting/unable-to-see-trace.md
Checklist
knylander-grafana commented 2 years ago

I"ll work on this as soon as PR#1512 is merged. (Waiting on issue with CLA assistant)

knylander-grafana commented 2 years ago

Working on this today

knylander-grafana commented 2 years ago

There are three pages related to backend search: the main page and two sub pages that describe different configurations. I'm going to make these sub pages son, so the page title doesn't match the H1. 

ERROR: docs/tempo/website/operations/serverless_aws.md: The first heading "AWS Lambda for serverless backend search" does not match the title "Backend search - serverless AWS setup" in the file docs/tempo/website/operations/serverless_aws.md

ERROR: docs/tempo/website/operations/serverless_gcp.md: The first heading "Google Cloud Run for serverless backend search" does not match the title "Backend search - serverless GCP setup" in the file docs/tempo/website/operations/serverless_gcp.md

The version titles and H1s were also not update: 

ERROR: docs/tempo/website/release-notes/v1-2.md: The first heading "Version 1.2 release notes" does not match the title "V1.2" in the file docs/tempo/website/release-notes/v1-2.md

ERROR: docs/tempo/website/release-notes/v1-3.md: The first heading "Version 1.3 release notes" does not match the title "V1.3" in the file docs/tempo/website/release-notes/v1-3.md

ERROR: docs/tempo/website/release-notes/v1-4.md: The first heading "Version 1.4 release notes" does not match the title "V1.4" in the file docs/tempo/website/release-notes/v1-4.md