Rebrand and update lightstep docs #13779

robswhitmore · 2023-08-28T20:40:56Z

Please provide a description for what this PR is for.

Lightstep has been rebranded to Cloud Observability from ServiceNow. Additionally, we now use the OpenTelemetry Collector to ingest metrics, traces, and logs from third-parties. These updates include both changes.

And to help us figure out who should review this PR, please
put an X in all the areas that this PR affects.

…rocedures to use OpenTelemetry

…update procedures to use OpenTelemetry" This reverts commit 25a4d05.

istio-policy-bot · 2023-08-28T20:41:00Z

😊 Welcome! This is either your first contribution to the Istio documentation repo, or
it's been awhile since you've been here. A few things you should know:

You can learn about how we write and maintain documentation, about our style guidelines,
and about all the available web site features by visiting Contributing to the Docs.
In the next few minutes, an automatic preview of your change will be
built as a full copy of the istio.io website. You can find this preview by clicking on
the Details link next to the deploy/netlify entry in the Status section of this
page.
We care about quality, so we've put in place a number of checks to ensure our documentation
is top notch. We do spell checking, we sanitize the markdown, we ensure all hyperlinks point
to valid location, and more. If your PR doesn't pass one of these checks, you'll see a red X in the
status section of the page. Click on the Details link to get a list of the problems with your PR.
Fix those problems and push an update to your PR. This will automatically rerun the tests and
hopefully this time everything will be perfect.
Once your changes are accepted and merged into the repository, they will initially show up
on https://preliminary.istio.io. The changes will be published to https://istio.io
the next time we do a major release (which typically happens every 3 months or so).

Thanks for contributing!

Courtesy of your friendly welcome wagon.

linux-foundation-easycla · 2023-08-28T20:41:02Z

The committers listed above are authorized under a signed CLA.

✅ login: robswhitmore / name: Robin Whitmore (25a4d05, f29ffbe, b7a0803, 13039b7, b3bcaa3, 8d10b62, 1e7d7b7, a56f7c0, 79e1bff, 474cebc, 9c381e7, 5aaeaf6, d5c1904, 8c1be73)

istio-testing · 2023-08-28T20:41:07Z

Hi @robswhitmore. Thanks for your PR.

I'm waiting for a istio member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

robswhitmore · 2023-08-28T20:48:29Z

I'd like to also add the label cherrypick/release-1.19 but I don't seem to be able to edit the labels field.

ericvn · 2023-08-29T00:00:32Z

/ok-to-test

ericvn · 2023-08-29T00:01:09Z

Depending on when this merges, it may or may not need the 1.19 label as there is no 1.19 branch (right now). The branch will be created when 1.19.0 is release.d.

Arhell

/ok-to-test

robswhitmore · 2023-08-29T14:45:19Z

I fixed the lint errors that I can, but the errors for spacing around lists can't be fixed because those are inside yaml code blocks. What should I do?

Also, what should we tag this PR so that it goes into the latest release?

dhawton · 2023-08-29T15:06:20Z

I fixed the lint errors that I can, but the errors for spacing around lists can't be fixed because those are inside yaml code blocks. What should I do?

Also, what should we tag this PR so that it goes into the latest release?

The errors are:

./en/docs/tasks/observability/distributed-tracing/lightstep/index.md:79: MD029 Ordered list item prefix
./en/docs/tasks/observability/distributed-tracing/lightstep/index.md:211: MD029 Ordered list item prefix
./en/docs/tasks/observability/distributed-tracing/lightstep/index.md:223: MD029 Ordered list item prefix

This has to do with you incrementing the numbers. All ordered list items must be 1.. They will get incremented automatically. IE on line 79 you have 2., it should be 1. Our style is one as documented here: https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md#md029---ordered-list-item-prefix

ericvn · 2023-08-29T15:27:11Z

We can work on getting the PR into the latest releases once it's ready to merge. It'll first go into the preliminary.istio.io docs and ten we will cherry-pick to the branch that corresponds to istio.io. That branch is changing soon, so timing will dictate where we cherry-pick.

ericvn · 2023-08-29T15:27:45Z

@istio/wg-policies-and-telemetry-maintainers Can you review this as owners of the page as well. Thanks.

ericvn · 2023-08-29T15:29:16Z

Also, note that you can click on the Details to the right of the deploy-preview job to get at the docs corresponding to this change. https://deploy-preview-13779--preliminary-istio.netlify.app/latest/docs/tasks/observability/distributed-tracing/lightstep/ would be the new page.

ericvn

I believe these 3 suggestions will fix the numbering. Looks like the line numbering is off by 1.

content/en/docs/tasks/observability/distributed-tracing/lightstep/index.md

…tep/index.md Co-authored-by: Eric Van Norman <ericvn@us.ibm.com>

lei-tang · 2023-08-29T16:42:11Z

content/en/docs/tasks/observability/distributed-tracing/lightstep/index.md

-that the call took 15.30 ms. The second span is labeled with the `reviews.default.svc.cluster.local:9080/*` operation
-and the `reviews.default: proxy server` service. The second span is a child of the first span and represents the
-server-side span of the call. The screenshot shows that the call took 14.60 ms.
+## View metrics in Cloud Observability


The folder content/en/docs/tasks/observability/distributed-tracing/lightstep is for tracing. Consider placing the metric guide into a different folder.

Moved to the metrics section

lei-tang · 2023-08-29T16:45:05Z

content/en/docs/tasks/observability/distributed-tracing/lightstep/index.md

 aliases:
 - /docs/tasks/telemetry/distributed-tracing/lightstep/
 owner: istio/wg-policies-and-telemetry-maintainers
 test: no
 ---

-{{< boilerplate telemetry-tracing-tips >}}
+You use the [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) to send Istio metrics to Cloud Observability using Istio proxies within each pod. Metrics are collected and forwarded to the OpenTelemetry Collector, which acts as a central collection and processing point and then sends those metrics to Cloud Observability.


The folder content/en/docs/tasks/observability/distributed-tracing/lightstep is for tracing. Consider placing the metric guide into a different folder.

Moved to the metrics section

Removed references to Lightstep in site where it was mentioned in the context of tracing (this also fixed broken links caused when moving the topics from Tracing to Metrics). There is still a broken link in /news/releases/1.1.x/announcing-1.1/change-notes/, but I don't think I should change that, right?

…ed. Removed mentions of trace data and adjusted the title and description accordingly.

…cing. Updated page alias

robswhitmore · 2023-08-29T23:32:37Z

/test lint

robswhitmore · 2023-08-30T00:02:31Z

I don't think I can fix this link because it's in a news post, right? The link goes to /news/releases/1.1.x/announcing-1.1/change-notes/

robswhitmore · 2023-09-06T00:07:22Z

@lei-tang or whoever else might be able to help -
The linter is failing with a broken link to an old change note. I don't think I should update this, correct?

lei-tang · 2023-09-06T00:22:13Z

@ericvn Do you have suggestions for fixing the broken link error above?

content/en/docs/tasks/observability/metrics/lightstep/index.md

ericvn · 2023-09-06T01:57:12Z

Lint error is Running linkinator...
[404] http://localhost:5080/docs/tasks/observability/distributed-tracing/lightstep/
ERROR: Detected 1 broken links. Scanned 5787 links in 39.311 seconds.

You removed this file so makes sense that the link isn't found.

What do you want people who pointed to it to point to now? You could point to an older release's version of the file by changing the URL to point to a specific older release. Maybe you want to add an alias to a new page so the page would then be used for the deleted page (ie. replace the alias I've asked you to remove with /docs/tasks/observability/distributed-tracing/lightstep/).

ericvn · 2023-09-06T02:22:03Z

Also added the cherry-pick label since we have cut the new branch.

robswhitmore · 2023-09-06T23:03:24Z

@ericvn I did what you suggested and changed the alias to the page I deleted (/docs/tasks/observability/distributed-tracing/lightstep/), but I'm still getting the same broken link and now an additional broken link for that alias. I followed the directions here, but I must be missing something?

dhawton · 2023-09-06T23:10:23Z

@ericvn I did what you suggested and changed the alias to the page I deleted (/docs/tasks/observability/distributed-tracing/lightstep/), but I'm still getting the same broken link and now an additional broken link for that alias. I followed the directions here, but I must be missing something?

The lint report tells you the file the link is originating from, which is https://github.com/robswhitmore/istio.io/blob/robswhitmore/rebrand-update-lightstep/content/en/news/releases/1.1.x/announcing-1.1/change-notes/index.md?plain=1#L165

Since you're changing the name of the file, link to an archived version of the page, for example: https://istio.io/v1.18/docs/tasks/observability/distributed-tracing/lightstep/

ericvn · 2023-09-07T00:20:44Z

@robswhitmore Daniel is correct. There are two ways to fix the issue. One is to update the link which is pointing to the file you removed in news/releases/1.1.x/announcing-1.1/change-notes/ to point to and older existing version of the page (use 1.19 or 1.18 for example). You can look at a commit where I did that yesterday: fbb5c8d prefixing https://archive.istio.io/v1.17 to the /docs/... that was removed. In this case, the link will point to the same information as before.

As I noted, if the new page you replaced the deleted page with is an acceptable alternative, then you can simply add /docs/tasks/observability/distributed-tracing/lightstep/ to the aliases list on the new page, and when they click the link it will take them to the new page. (Edit: It looks like you did this. Maybe it's a formatting issue and the items need to be indented 4 spaces).

Pick whichever way yields the best information to the reader.

ericvn · 2023-09-07T00:25:41Z

content/en/docs/tasks/observability/metrics/lightstep/index.md

+weight: 11
+keywords: [telemetry, metrics ,lightstep, servicenow, cloud observability]
+aliases:
+ - /docs/tasks/observability/distributed-tracing/lightstep/


I'm wondering if there is a format issue with number of leading spaces, as this does look correct. Need to try pulling your PR and trying the link-check locally.

Suggested change

- /docs/tasks/observability/distributed-tracing/lightstep/

- /docs/tasks/observability/distributed-tracing/lightstep/

Basically, the alias discussion is here: https://istio.io/latest/docs/releases/contribute/front-matter/#rename-move-or-delete-pages

I did pull your branch locally and try a few things with the aliases, and I never got it to work. I guess I would just do option 1 and update the 1 link to point to the archive and remove the alias.

@frankbu is there some magic on the aliases:?

ericvn · 2023-09-07T00:43:12Z

content/en/docs/tasks/observability/metrics/lightstep/index.md

+---
+title: Viewing Istio Metrics in Cloud Observability from ServiceNow
+description: This task shows you how to use OpenTelemetry to ingest and view Istio metrics in Cloud Observability (formerly Lightstep).
+weight: 11


Also the weight here is used to set the order of the links within the page. You can look at your preview at https://deploy-preview-13779--preliminary-istio.netlify.app/latest/docs/tasks/observability/metrics/ to see if the orderings correct. Higher numbers go down the order.

robswhitmore · 2023-09-07T18:29:10Z

@ericvn and @lei-tang - my commit finally passed the lint check, so I think it's good to go. Thanks for all your help!

lei-tang · 2023-09-07T18:43:34Z

content/en/docs/tasks/observability/metrics/lightstep/index.md

+
+## Configure Istio Operator
+
+Create an `istio-operator.yaml` file by copying the following code.


Is 'istio-operator.yaml' here used in the guide? A quick search did not return any results.

I'm not sure what you mean by "used in the guide?" Do you mean elsewhere in Istio docs? It's used in this topic to configure the k8s operator for Istio.

I mean whether 'istio-operator.yaml' is used in this guide.

"It's used in this topic to configure the k8s operator for Istio."

Which command lines in this guide use 'istio-operator.yaml'?

I think what @lei-tang is saying is that the instructions have you creating a number of files, like otel-collector-configmap.yaml and otel-collector-deployment.yaml and you look at the directions in the next sections, you can see kubectl apply -f for these files. The question is where is there an instruction that actually uses the 'istio-operator.yaml' file.

And if there is no usage for the file, why are we creating it on this page?

Thanks - I realized what he was asking and agreed, so I sent it back to the engineering team. They are working on updates.Thanks for catching that - I definitely should have, but with this rebrand, I've been 🤪!

ericvn · 2023-10-17T01:32:53Z

Does #13996 replace this?

robswhitmore · 2023-10-17T13:42:23Z

News to me! 😕 Let me find out what's going on...

robswhitmore · 2023-10-30T18:45:10Z

Looks like the eng team decided to focus on Tracing, so that new PR is separate from this one, and is taking precedence. Sorry for all the confusion!

ericvn · 2023-12-06T17:32:23Z

Looks like the eng team decided to focus on Tracing, so that new PR is separate from this one, and is taking precedence. Sorry for all the confusion!

I think you are saying that at some point this PR will be revisited.

robswhitmore · 2023-12-06T19:30:05Z

Yes, at some point. Thanks -

Change request made.

istio-testing · 2024-03-06T22:04:15Z

PR needs rebase.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

robswhitmore added 3 commits August 28, 2023 12:51

rebrand Lightstep to Cloud Observability from ServiceNow and update p…

25a4d05

…rocedures to use OpenTelemetry

Revert "rebrand Lightstep to Cloud Observability from ServiceNow and …

f29ffbe

…update procedures to use OpenTelemetry" This reverts commit 25a4d05.

rebrand Lightstep to Cloud Observability and update to use OpenTelemetry

b7a0803

robswhitmore requested a review from a team as a code owner August 28, 2023 20:40

istio-policy-bot added the kind/docs label Aug 28, 2023

istio-testing added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. needs-ok-to-test labels Aug 28, 2023

istio-testing added ok-to-test Set this label allow normal testing to take place for a PR not submitted by an Istio org member. and removed needs-ok-to-test labels Aug 29, 2023

Arhell reviewed Aug 29, 2023

View reviewed changes

fix lint errors

13039b7

dhawton changed the title ~~Robswhitmore/rebrand update lightstep~~ Rebrand and update lightstep docs Aug 29, 2023

ericvn reviewed Aug 29, 2023

View reviewed changes

robswhitmore and others added 3 commits August 29, 2023 09:41

Update content/en/docs/tasks/observability/distributed-tracing/lights…

b3bcaa3

…tep/index.md Co-authored-by: Eric Van Norman <ericvn@us.ibm.com>

Update content/en/docs/tasks/observability/distributed-tracing/lights…

8d10b62

…tep/index.md Co-authored-by: Eric Van Norman <ericvn@us.ibm.com>

Update content/en/docs/tasks/observability/distributed-tracing/lights…

1e7d7b7

…tep/index.md Co-authored-by: Eric Van Norman <ericvn@us.ibm.com>

lei-tang reviewed Aug 29, 2023

View reviewed changes

robswhitmore added 2 commits August 29, 2023 11:05

moved topic to metrics because this integration is now metrics-center…

a56f7c0

…ed. Removed mentions of trace data and adjusted the title and description accordingly.

merge changes

79e1bff

robswhitmore added 2 commits August 29, 2023 15:55

remove Lightstep from pages in site that reference it in terms of tra…

9c381e7

…cing. Updated page alias

fix alias

5aaeaf6

ericvn previously requested changes Sep 6, 2023

View reviewed changes

content/en/docs/tasks/observability/metrics/lightstep/index.md Outdated Show resolved Hide resolved

ericvn added the cherrypick/release-1.19 Set this label on a PR to auto-merge it to the release-1.19 branch label Sep 6, 2023

fix alias to be the retired page to allow redirects

d5c1904

ericvn reviewed Sep 7, 2023

View reviewed changes

fix link to point to old version of lightstep

8c1be73

lei-tang reviewed Sep 7, 2023

View reviewed changes

ericvn removed the cherrypick/release-1.19 Set this label on a PR to auto-merge it to the release-1.19 branch label Nov 16, 2023

istio-policy-bot added the lifecycle/stale Indicates a PR or issue hasn't been manipulated by an Istio team member for a while label Nov 16, 2023

istio-policy-bot removed the lifecycle/stale Indicates a PR or issue hasn't been manipulated by an Istio team member for a while label Dec 6, 2023

istio-testing added the needs-rebase Indicates a PR needs to be rebased before being merged label Mar 6, 2024

	- /docs/tasks/observability/distributed-tracing/lightstep/
	- /docs/tasks/observability/distributed-tracing/lightstep/


		## Configure Istio Operator

		Create an `istio-operator.yaml` file by copying the following code.

Rebrand and update lightstep docs #13779

Are you sure you want to change the base?

Rebrand and update lightstep docs #13779

Conversation

robswhitmore commented Aug 28, 2023

istio-policy-bot commented Aug 28, 2023

linux-foundation-easycla bot commented Aug 28, 2023 • edited

istio-testing commented Aug 28, 2023

robswhitmore commented Aug 28, 2023

ericvn commented Aug 29, 2023

ericvn commented Aug 29, 2023

Arhell left a comment

Choose a reason for hiding this comment

robswhitmore commented Aug 29, 2023

dhawton commented Aug 29, 2023 • edited

ericvn commented Aug 29, 2023

ericvn commented Aug 29, 2023

ericvn commented Aug 29, 2023

ericvn left a comment • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

robswhitmore commented Aug 29, 2023

robswhitmore commented Aug 30, 2023 • edited

robswhitmore commented Sep 6, 2023

lei-tang commented Sep 6, 2023

ericvn commented Sep 6, 2023 • edited

ericvn commented Sep 6, 2023

robswhitmore commented Sep 6, 2023

dhawton commented Sep 6, 2023

ericvn commented Sep 7, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

robswhitmore commented Sep 7, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lei-tang Sep 7, 2023 • edited

Choose a reason for hiding this comment

ericvn Sep 8, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ericvn commented Oct 17, 2023

robswhitmore commented Oct 17, 2023

robswhitmore commented Oct 30, 2023

ericvn commented Dec 6, 2023

robswhitmore commented Dec 6, 2023

istio-testing commented Mar 6, 2024

linux-foundation-easycla bot commented Aug 28, 2023 •

edited

dhawton commented Aug 29, 2023 •

edited

ericvn left a comment •

edited

robswhitmore commented Aug 30, 2023 •

edited

ericvn commented Sep 6, 2023 •

edited

ericvn commented Sep 7, 2023 •

edited

lei-tang Sep 7, 2023 •

edited

ericvn Sep 8, 2023 •

edited