added the right pointer for OTLP endpoint #7375

zhehao-grafana · 2024-02-14T01:58:12Z

What this PR does

It is used to point to the right OTLP sources on cloud so people don't use the wrong one

Which issue(s) this PR fixes or relates to

Fixes #

Checklist

Tests updated.
Documentation added.
CHANGELOG.md updated - the order of entries should be [CHANGE], [FEATURE], [ENHANCEMENT], [BUGFIX].
about-versioning.md updated with experimental features.

CLAassistant · 2024-02-14T01:58:17Z

All committers have signed the CLA.

zhehao-grafana · 2024-02-14T01:59:12Z

@aknuds1 @fayzal-g @jdbaldry I assume this is the right place to replace the original PR

aknuds1 · 2024-02-14T12:00:00Z

Having a look.

aknuds1

Apart from my specific comment, I wonder if we shouldn't be editing Grafana Cloud documentation instead, making sure that (Grafana Cloud) users are directed towards the OTel Gateway instead (as opposed to using the Mimir OTLP endpoint directly.

Having thought it over again, I see that the point of these admonitions should be to steer readers of Grafana Cloud documentation away from using the Mimir OTLP endpoint directly. I wonder though if we have the ability to put the admonitions into the Grafana Cloud docs sources instead, so they get merged with Mimir docs sources? Maybe we're not able to 🤷

You also need make doc locally to fix the formatting, and pass CI.

aknuds1 · 2024-02-14T12:14:39Z

docs/sources/mimir/configure/configure-otel-collector.md

@@ -61,6 +61,9 @@ service:
 ```

 ## OTLP
+{{% admonition type="note" %}} 
+If you are on Grafana Cloud, please use the OpenTelemetry Protocol (OTLP), and you can find more information [here] (https://grafana.com/docs/grafana-cloud/send-data/otlp/send-data-otlp/).


I don't think it makes sense to say to use OTLP, since this section is in fact about using OTLP. What we want to instead is to recommend using the OTel Gateway endpoint in Grafana Cloud.

Also fixing the link while I'm here. I recall furthermore that our documentation style guidelines say to use something more descriptive than "here", for links.

Suggested change

If you are on Grafana Cloud, please use the OpenTelemetry Protocol (OTLP), and you can find more information [here] (https://grafana.com/docs/grafana-cloud/send-data/otlp/send-data-otlp/).

If you are on Grafana Cloud, please use the OpenTelemetry Gateway, which you can find more information on in [this guide](https://grafana.com/docs/grafana-cloud/send-data/otlp/send-data-otlp/).

As @aknuds1 has pointed out, it is important to write useful link text for those reading the documentation on a screen reader.

For guidance, refer to Useful link text

I don't think it makes sense to say to use OTLP, since this section is in fact about using OTLP. What we want to instead is to recommend using the OTel Gateway endpoint in Grafana Cloud.

I agree, perhaps the following, also applied to the other note.

Suggested change

If you are on Grafana Cloud, please use the OpenTelemetry Protocol (OTLP), and you can find more information [here] (https://grafana.com/docs/grafana-cloud/send-data/otlp/send-data-otlp/).

To send OTLP data to Grafana Cloud, refer to [Send data using OpenTelemetry Protocol (OTLP)](https://grafana.com/docs/grafana-cloud/send-data/otlp/send-data-otlp/).

I also think the note makes sense at the beginning of this page rather than under the OTLP heading.

@jdbaldry do you think it's problematic at all to include Grafana Cloud specifics in Mimir OSS docs? I'm uncertain whether we have a policy on this, or not (re: my wondering on whether we could merge in the admonitions from Grafana Cloud docs sources).

I actually like @jdbaldry's suggestion better than my own, especially since it doesn't mention OTel Gateway (which may be replaced in the future).

do you think it's problematic at all to include Grafana Cloud specifics in Mimir OSS docs?

That's a great question that I'm not certain of the answer to. I will find out and get back to you.

Another interesting question.

I am not certain about the intention of this page but at a scan, I believed it to be a task intending to help the user write OpenTelemetry metrics to Mimir. In that case I think it makes sense to tell them as early as possible in the process.

I'm not sure if I would expect users to be linked directly to the OTLP heading unless they are certainly interested in sending to OSS Mimir.

@jdbaldry ah my bad, I was confusing this change and the other one. The latter is the HTTP API reference page, and is for a lot more than just OTel. Never mind :) My comment in this regard only makes sense for the HTTP API change.

No worries at all, I think for HTTP API you are absolutely right. I'd also consider leaving out the note in that page because I think it is less relevant there. I'm on the fence to be honest. Let's see what the rest of the doc squad has to say about Grafana Cloud notes in OSS docs first :)

Got some feedback on that actually, it's fine to have Grafana Cloud notes in the docs, especially if it eliminates confusion.

Thanks for figuring this out @jdbaldry!

aknuds1 · 2024-02-14T12:15:06Z

docs/sources/mimir/references/http-api/index.md

@@ -317,6 +317,9 @@ Requires [authentication](#authentication).
 ```
 POST /otlp/v1/metrics
 ```
+{{% admonition type="note" %}}
+If you are on Grafana Cloud, please use the OpenTelemetry Protocol (OTLP), and you can find more information [here] (https://grafana.com/docs/grafana-cloud/send-data/otlp/send-data-otlp/).


See my comment above. Copying @jdbaldry's suggestion ;)

Suggested change

If you are on Grafana Cloud, please use the OpenTelemetry Protocol (OTLP), and you can find more information [here] (https://grafana.com/docs/grafana-cloud/send-data/otlp/send-data-otlp/).

To send OTLP data to Grafana Cloud, refer to [Send data using OpenTelemetry Protocol (OTLP)](https://grafana.com/docs/grafana-cloud/send-data/otlp/send-data-otlp/).

jdbaldry

Thanks for the contribution @zhehao-grafana!

To summarize the discussion and next steps:

I believe both notes should be updated to instead use the following text:

To send OTLP data to Grafana Cloud, refer to Send data using OpenTelemetry Protocol (OTLP).
I believe the note in docs/sources/mimir/configure/configure-otel-collector.md should be moved to the top of the page as part of the introduction text.
You need to sign the CLA so that we can accept your changes.

zhehao-grafana · 2024-02-15T02:33:52Z

updated the file by comment

@jdbaldry Thanks for the review! Do you mind taking a look at the latest change I made?

jdbaldry

Nearly there, thanks for considering our suggestions!

https://github.com/grafana/mimir/pull/7375/files#diff-027d0564bef402ca0e98549c7f5ceb3fcfbdb1e8d2fc78b667d1bf360cbd6059L63-L64
looks to be an accidental deletion. If you can restore those two lines, this is good to go!

zhehao-grafana · 2024-02-15T23:09:24Z

Nearly there, thanks for considering our suggestions!

https://github.com/grafana/mimir/pull/7375/files#diff-027d0564bef402ca0e98549c7f5ceb3fcfbdb1e8d2fc78b667d1bf360cbd6059L63-L64 looks to be an accidental deletion. If you can restore those two lines, this is good to go!

please review the latest change. @jdbaldry

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

Signed-off-by: Arve Knudsen <arve.knudsen@gmail.com>

added the right pointer for OTLP endpoint

1fcfb3d

zhehao-grafana requested review from a team as code owners February 14, 2024 01:58

aknuds1 reviewed Feb 14, 2024

View reviewed changes

jdbaldry reviewed Feb 14, 2024

View reviewed changes

updated the file by comment

d022d47

jdbaldry requested changes Feb 15, 2024

View reviewed changes

added lines back

df7480a

jdbaldry approved these changes Feb 16, 2024

View reviewed changes

Prettier

9b00d7e

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

jdbaldry force-pushed the mimir-otlp-context branch from e9db13e to 9b00d7e Compare February 19, 2024 13:01

aknuds1 approved these changes Feb 19, 2024

View reviewed changes

aknuds1 added type/docs Improvements or additions to documentation enhancement New feature or request area/opentelemetry labels Feb 19, 2024

aknuds1 added 2 commits February 19, 2024 14:16

Merge remote-tracking branch 'origin/main' into mimir-otlp-context

52f1f73

Add changelog entry

5e82f6f

Signed-off-by: Arve Knudsen <arve.knudsen@gmail.com>

aknuds1 enabled auto-merge (squash) February 19, 2024 13:19

aknuds1 merged commit 3398d5e into main Feb 19, 2024
28 checks passed

aknuds1 deleted the mimir-otlp-context branch February 19, 2024 13:32

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

added the right pointer for OTLP endpoint #7375

added the right pointer for OTLP endpoint #7375

zhehao-grafana commented Feb 14, 2024

CLAassistant commented Feb 14, 2024 •

edited

Loading

zhehao-grafana commented Feb 14, 2024

aknuds1 commented Feb 14, 2024

aknuds1 left a comment •

edited

Loading

aknuds1 Feb 14, 2024 •

edited

Loading

jdbaldry Feb 14, 2024

aknuds1 Feb 14, 2024

aknuds1 Feb 14, 2024 •

edited

Loading

jdbaldry Feb 14, 2024

jdbaldry Feb 14, 2024

aknuds1 Feb 14, 2024 •

edited

Loading

jdbaldry Feb 14, 2024

jdbaldry Feb 14, 2024

aknuds1 Feb 14, 2024

aknuds1 Feb 14, 2024 •

edited

Loading

jdbaldry left a comment

zhehao-grafana commented Feb 15, 2024

jdbaldry left a comment

zhehao-grafana commented Feb 15, 2024

	If you are on Grafana Cloud, please use the OpenTelemetry Protocol (OTLP), and you can find more information [here] (https://grafana.com/docs/grafana-cloud/send-data/otlp/send-data-otlp/).
	If you are on Grafana Cloud, please use the OpenTelemetry Gateway, which you can find more information on in [this guide](https://grafana.com/docs/grafana-cloud/send-data/otlp/send-data-otlp/).

	If you are on Grafana Cloud, please use the OpenTelemetry Protocol (OTLP), and you can find more information [here] (https://grafana.com/docs/grafana-cloud/send-data/otlp/send-data-otlp/).
	To send OTLP data to Grafana Cloud, refer to [Send data using OpenTelemetry Protocol (OTLP)](https://grafana.com/docs/grafana-cloud/send-data/otlp/send-data-otlp/).

added the right pointer for OTLP endpoint #7375

added the right pointer for OTLP endpoint #7375

Conversation

zhehao-grafana commented Feb 14, 2024

What this PR does

Which issue(s) this PR fixes or relates to

Checklist

CLAassistant commented Feb 14, 2024 • edited Loading

zhehao-grafana commented Feb 14, 2024

aknuds1 commented Feb 14, 2024

aknuds1 left a comment • edited Loading

Choose a reason for hiding this comment

aknuds1 Feb 14, 2024 • edited Loading

Choose a reason for hiding this comment

jdbaldry Feb 14, 2024

Choose a reason for hiding this comment

aknuds1 Feb 14, 2024

Choose a reason for hiding this comment

aknuds1 Feb 14, 2024 • edited Loading

Choose a reason for hiding this comment

jdbaldry Feb 14, 2024

Choose a reason for hiding this comment

jdbaldry Feb 14, 2024

Choose a reason for hiding this comment

aknuds1 Feb 14, 2024 • edited Loading

Choose a reason for hiding this comment

jdbaldry Feb 14, 2024

Choose a reason for hiding this comment

jdbaldry Feb 14, 2024

Choose a reason for hiding this comment

aknuds1 Feb 14, 2024

Choose a reason for hiding this comment

aknuds1 Feb 14, 2024 • edited Loading

Choose a reason for hiding this comment

jdbaldry left a comment

Choose a reason for hiding this comment

zhehao-grafana commented Feb 15, 2024

jdbaldry left a comment

Choose a reason for hiding this comment

zhehao-grafana commented Feb 15, 2024

CLAassistant commented Feb 14, 2024 •

edited

Loading

aknuds1 left a comment •

edited

Loading

aknuds1 Feb 14, 2024 •

edited

Loading

aknuds1 Feb 14, 2024 •

edited

Loading

aknuds1 Feb 14, 2024 •

edited

Loading

aknuds1 Feb 14, 2024 •

edited

Loading