In-product shows Monitor features that are being deprecated

Summary

This issue keep tracks of in-app notification and change requirements for Monitor related deprecations in %15.0.

Proposed Changes

1. Display an alert at the top of the Metrics, Logs, Tracing, and Settings > Monitor pages.
2. Alert will communicate what's happening, how this will impact people, and what the plan is for replacing these features:

• scheduled for removal, links to - &7188 (closed)
• learn more about Opstrace, links to - &6976 (closed)

changed milestone to %14.8

added devopsmonitor grouprespond sectionops labels

added to epic &7188 (closed)

mentioned in issue #346541 (closed)

mentioned in issue #346540 (closed)

mentioned in issue #346485 (closed)

mentioned in issue gitlab-org/monitor/respond#100 (closed)

added Deliverable label

changed the description

mentioned in epic &7188 (closed)

@ameliabauerly - here are my ideas for in-app notifications about the Metrics, Logging and Tracing deprecations.

1. Is there a design precedent for deprecating features like this?
2. At first glance, it looks like the navigation will just require removals for the items that are deprecated in %15.0.

WDYT?

@abellucci - Thanks for creating this issue! There are a number of areas in the UI that will be impacted by this change. I'll create separate sections for each. But, for reference, here is the deprecation epic the Configure team put together when we deprecated gitlab-managed apps (and thus the alerts on the metrics dashboard).

Adding deprecation alerts on each of the impacted pages

This is something either we (or the Observability team) should do this milestone.

Is there a design precedent for deprecating features like this?

Yes, there is. We can follow the same pattern we used when we deprecated alerts. Essentially, the in-app notification is an alert displayed at the top of each page being deprecated. On this issue, you can see the text we used for the alerts deprecation. Here is some sample text in the alert styling, but we'd need to work with @ngaskill to confirm the text. (Note: date is placeholder for now; we'll need to confirm when the dashboards will actually disappear!)

We'll need to add one of these messages to each of the three impacted pages. I currently have it in the orange "warning" style. We may want to bump that up to a "critical" warning since I'm guessing those pages will be disappearing entirely for those users, and we don't want them to miss the message.

Docs deprecation notices

It looks like some of the deprecation notices have been added into the docs already, but I notice we might have missed out this page: https://docs.gitlab.com/ee/operations/metrics/. Also, is there maybe a blog post or something we can link people to, so they have some sense of why these pages are being deprecated, and what will replace them?

Navigation changes

The current Metrics, Logs and Tracing pages will be deprecated. I don't think we've ever added text to the sidebar for deprecations; I'd worry that surfacing that information so prominently would make the product feel a bit broken.

We can leave the pages in the navigation and visible for the short-term with some sort of empty state letting people know that the previous page has been deprecated, and explain what will be replacing them. Having our Monitor navigation link to three deprecated pages probably isn't great, in terms of experience, though. So I'd think that, once they are deprecated, those pages would ultimately disappear from the navigation, perhaps after a month or two.

@tauriedavis - I know you are the DRI for navigation changes now. Metrics, Tracing and Logs are being deprecated in 15.0 (to be replaced with OpsTrace, at some point in the future). I'm assuming these items would drop from the navigation but, maybe there's another pattern you'd recommend?

Settings changes in Settings > Monitor

We can add "deprecated" text to the Metrics and Tracing sections, and disable all the elements within them for a milestone or two. Longer-term, though, we should probably just be removing those sections from the settings page entirely, to ensure this page isn't cluttered with unused settings items.

Also, we might want to check with the team about the Grafana section. While it was originally intended as a way to replace the Metrics dashboard with a link to Grafana, I'm not sure that's all it's used for. We can also embed links to Grafana metrics in, say, GitLab issues/incidents. I'm wondering if removing that section will also remove the ability to embed Grafana charts in GFM entirely. Perhaps @syasonik can confirm? I guess I just want to make sure we can safely remove/deprecate this section without impacting anything else.

General Settings changes

In Settings > Visibility, there are also some changes we'll need to make. The big one is that we'd need to remove this Metrics Dashboard toggle:

As a sidenote, this settings section still hasn't been updated since Operations was split up into Monitor, Deployments and Infrastructure. There's a separate issue for that work; just letting you know why it's still called Operations!

Visibility by tier

We'll need to define what the "default" navigation item will be when someone clicks on "Monitor" in the left-navigation. Right now, if someone clicks on Monitor, they will see the Metrics dashboard. I think, if we don't change this, users would just see a 404

I believe Error Tracking is available on the free tier, and would thus be visible for all users (though we should confirm this). Also, since it will presumably be the top item in the navigation once Metrics, Tracing and Logs disappear, it will probably also become the new "default" option when people click on Monitor in the nav. But, I'm guessing we'll need to go in and clean-up some code to ensure this is the case, and people don't see a 404.

There's quite a lot here. I don't know how this work will break down between Respond/Observability but, at least getting those deprecation notices up will be a great first step. I'll add this to the team meeting today since the team might also have ideas about things that will be impacted that I've missed!

@ameliabauerly I added some guidelines around messaging nav changes to users in Pajamas: https://design.gitlab.com/regions/navigation#messaging-changes-to-users. This was primarily for top-level nav items but could be applied to sub-nav items as well.

Cool, thanks! @abellucci - there is some guidance here:

Advanced: An advanced page-level info alert is required if an item has equal to or greater than 0.1% of clicks per active user per month. Advanced notice should be in place for at least one milestone.

I don't know what the clicks are for those three pages but, since they are likely just going to disappear, I'd think we'd want to go this route, regardless of clicks.

We can also embed links to Grafana metrics in, say, GitLab issues/incidents. I'm wondering if removing that section will also remove the ability to embed Grafana charts in GFM entirely. Perhaps @syasonik can confirm? I guess I just want to make sure we can safely remove/deprecate this section without impacting anything else.

@ameliabauerly Yes, the Grafana Authentication section controls Grafana embeds in GFM. So removing this section would remove those embeds. Grafana-rendered images should still work though, as that's ultimately a Grafana feature.

The setting to add a link to Grafana from the the Metrics dashboard is found under Settings > Monitor > Metrics > External dashboard URL.

@ameliabauerly It's important that we distinguish between deprecation and removal. They are different, but related:

• Deprecation: the feature is no longer in active development, and is scheduled for removal in the future. This serves as a warning for the user to migrate off the feature.
• Removal: the feature is no longer available in the product.

So when we deprecate things, we shouldn't remove the docs or nav items, because deprecated features are still functional and exist in the product. We just need to add a warnings with the following info:

• Deprecation milestone
• Removal milestone

I reviewed and merged several MRs to our docs that contain those warnings for Monitor::Respond, but I'm unsure if there are additional docs that still need them. cc @abellucci

Thanks for the additional information, @ngaskill. I believe we are both deprecating, and removing. We can include both in the message.

@abellucci, can you confirm metrics, logs and tracing are going to be deprecated, and removed? After deprecation, will these pages still be functional for users? Is there a date they will be removed by? Is full removal at the end of 15.0?

Sidenote for Alana, of the list of things that I posted in my earlier comment, it sounds like we'd probably just want to add the alert to the affected pages (and perhaps the corresponding settings items) in 14.8. I guess we could create separate issues for the other items and put them with the removal work?

@ameliabauerly - Thanks for picking this up! Here are some answers:

I believe we are both deprecating, and removing.

Correct! Let's include both in the message.

After deprecation, will these pages still be functional for users?

Correct! These pages/features were deprecated in %14.7, but are still functional for users. We're planning on doing a removal in the next major release, %15.0.

It sounds like we'd probably just want to add the alert to the affected pages (and perhaps the corresponding settings items) in %14.8.

That's what I had in mind for the scope of the issue. There will be a separate issue for the removal work.

Thanks for the feedback, @abellucci!

So, for the proposal for this specific issue, I'd recommend the following:

1. Display an alert at the top of the Metrics, Logs, Tracing and Settings > Monitor pages.
2. Alert could be generic enough to work on all four pages. My goal is to communicate what's happening, how this will impact people, and what the plan is for replacing these features. The text isn't quite right yet, but perhaps something like this:

I was thinking the first link could be a deprecation/removal notice, and the second one to, maybe, a blog post/announcement describing OpsTrace.

WDYT? @ngaskill, would also appreciate your thoughts on the text, as I know it isn't quite right yet.

I'll start updating this issue description now, and we can finalize the screenshot when we finalize the text

@ameliabauerly Here's a suggested edit:

The metrics, logs, and tracing features were deprecated in GitLab 14.7, and are scheduled for removal in GitLab 15.0. For information on a possible replacement, learn more about Opstrace.

I don't think we need to say that the pages will no longer be visible upon removal, since that's what removal is. For legal reasons, we need to avoid promising future functionality. So I've removed "will be replaced by...", in favor of "possible replacement".

cc @abellucci

Thanks, @ngaskill!

Here's the updated screenshot:

Do you have a sense of what it would be good to link to for both the removal and "learn more about Opstrace" links, @abellucci?

@ameliabauerly For the removal, we should link to the removal issue. For the Opstrace link, we should link to the Opstrace integration issue. However, I don't have the links to either of those issues

No worries, I bet Alana will know. I'll wait for her reply, and we can add that into the issue description

@ameliabauerly - Here is the Opstrace integration issue link - &6976 (closed). I went ahead and added the link to the Description above.

@ngaskill - for the removal issue are you referring something like this issue? Or the forthcoming removal entry? Or something else?

@abellucci I'm used to seeing separate issues for the deprecation and removal, but #346541 (closed) should work

@abellucci - since I'm proposing we use a single message for all the pages, and that issue is specifically for metrics, I wonder if we should instead link to the epic that will hold all of the metrics, tracing and log deprecation and removal work?

I'll tentatively add that to the issue description. I'll also mark this workflowready for development, just as I know someone will likely need to pick this up this week to get it merged this milestone. We can continue to refine links and such as the MR is being worked on, as long as we have a general plan in place

@abellucci - to loop back here - I created separate removal issues for the UI elements I highlighted in my original comment:

• #351388 (closed)
• #351387 (closed)
• #351389 (closed)
• #351390

I've added them all to this epic: &7188 (closed).

@tristan.read - I know you mentioned having separate issues for the code removals we'll need to do. Do the issues above cover that need, or do we need additional issues from an engineering POV?

@abellucci - also, do we need to add a deprecation notice to https://docs.gitlab.com/ee/operations/metrics/? It seems like we should?

Finally, Alana, is it worth flagging that this issue is needing to get picked up in our Slack channel or something, as I guess it would need to get completed/merged in the next couple weeks? I just noticed that it isn't currently being worked on, so maybe we should flag that it's needing someone to pick it up?

@ameliabauerly - Thanks for creating the separate removal issues for the UI elements! I've scheduled them all for %15.0.

Do we need to add a deprecation notice to https://docs.gitlab.com/ee/operations/metrics/?

I completely missed this page somehow in this MR. I've created a new MR to add the deprecation notice to this page.

@crystalpoole - is there someone that can work on this issue? I want to make sure this work get's done and merged in %14.8 so users have ample notice about these feature removals.

@tristan.read Do you have capacity for this in the current milestone? Or perhaps @rkadam3, is this something you could work on in the frontend?

Thanks, Alana!

I can take a look

I know you mentioned having separate issues for the code removals we'll need to do. Do the issues above cover that need, or do we need additional issues from an engineering POV?

Thanks for creating those issues, they should cover it from my perspective

Awesome, thanks for reviewing!

assigned to @ameliabauerly

added UX label

set weight to 4

@ameliabauerly Should the removal text note the date as 22 May 2022? Assuming the due date on https://gitlab.com/groups/gitlab-org/-/milestones/65 is accurate, this is when %15.0 will release for self-hosted customers.

Good point, @tristan.read! I wasn't sure what the actual date would be so I put the end of the next milestone in as a placeholder for now. Since the page is disappearing, it seemed like it might be good to be specific about when it will no longer function!

Happy to assume 22 May instead, if it's a more realistic cut-off date! I've also added a note to my earlier comment so that it's clearer that the listed date is a placeholder

Some further thoughts - usually deprecation happens immediately (in our case, %14.8 is the next release), and removal happens later, e.g. %15.0 assuming we follow past trends. If we do an immediate deprecation, the message should be something like Feature X is now deprecated, scheduled to be removed in 15.0, rather than referencing a future deprecation.

Gotcha, thanks for info!

added workflowdesign label

changed the description

changed the description

changed the description

@abellucci, please can you add a type label to this issue to help with issue discovery in issue reports.

added auto updated label

added workflowready for development label and removed workflowdesign label

changed the description

added typemaintenance label

mentioned in issue #351387 (closed)

unassigned @ameliabauerly

added [deprecated] Accepting merge requests label

assigned to @rkadam3

removed [deprecated] Accepting merge requests label

mentioned in merge request !79506 (merged)

added workflowin dev label and removed workflowready for development label

mentioned in issue #351667 (closed)

mentioned in merge request !80696 (merged)

All the required MRs for this issue are merged.

Is there anything left for this issue to be used in RP? @abellucci

Or we can close this?

@rkadam3 - Since we've already made the deprecation announcement in %14.7 we won't need to create a Release Post for this work. Thanks for double checking and great work getting this done for %14.8!

closed

added workflowproduction label and removed workflowin dev label

mentioned in issue #353145 (closed)

mentioned in epic &10107

mentioned in issue #348909 (closed)