[8.x] Add message in ua linking to deprecated debug logs docs (#208806)…

… (#209262) # Backport This will backport the following commits from `main` to `8.x`: - [Add message in ua linking to deprecated debug logs docs (#208806)](#208806)  ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sorenlouv/backport) \n\n### Questions ?\nPlease refer to the [Backport tool\ndocumentation](https://github.com/sqren/backport)\n\n\n\nCo-authored-by: Jesus Wahrman <[email protected]>"}},{"branch":"8.18","label":"v8.18.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"main","label":"v9.1.0","branchLabelMappingKey":"^v9.1.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/208806","number":208806,"mergeCommit":{"message":"Add message in ua linking to deprecated debug logs docs (#208806)\n\n## Summary\r\n\r\nResolves https://github.com/elastic/kibana/issues/208570\r\n\r\nAdd a message in UA with a link to the new config that enables debug\r\nlogs when a deprecated API is called.\r\n\r\n<img width=\"485\" alt=\"Screenshot 2025-01-29 at 17 16 33\"\r\nsrc=\"https://github.com/user-attachments/assets/ce796b38-c7af-4f0c-bcca-74512c909208\"\r\n/>\r\n\r\nTo try this you can call a deprecated API and look for the warnings in\r\nUA.\r\n\r\n### Checklist\r\n\r\nCheck the PR satisfies following conditions. \r\n\r\nReviewers should verify this PR satisfies this list as well.\r\n\r\n- [x] Any text added follows [EUI's writing\r\nguidelines](https://elastic.github.io/eui/#/guidelines/writing), uses\r\nsentence case text and includes [i18n\r\nsupport](https://github.com/elastic/kibana/blob/main/src/platform/packages/shared/kbn-i18n/README.md)\r\n- [x] [Unit or functional\r\ntests](https://www.elastic.co/guide/en/kibana/master/development-tests.html)\r\nwere updated or added to match the most common scenarios\r\n- [x] This was checked for breaking HTTP API changes, and any breaking\r\nchanges have been approved by the breaking-change committee. The\r\n`release_note:breaking` label should be applied in these situations.\r\n- [x] The PR description includes the appropriate Release Notes section,\r\nand the correct `release_note:*` label is applied per the\r\n[guidelines](https://www.elastic.co/guide/en/kibana/master/contributing.html#kibana-release-notes-process)\r\n\r\n### Identify risks\r\n\r\nDoes this PR introduce any risks? For example, consider risks like hard\r\nto test bugs, performance regression, potential of data loss.\r\n\r\nDescribe the risk, its severity, and mitigation for each identified\r\nrisk. Invite stakeholders and evaluate how to proceed before merging.\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine <[email protected]>\r\nCo-authored-by: florent-leborgne <[email protected]>","sha":"5774e8d402756a040037134c341b94d2dacd56ce"}},{"branch":"8.x","label":"v8.19.0","branchLabelMappingKey":"^v8.19.0$","isSourceBranch":false,"state":"NOT_CREATED"}]}] BACKPORT-->
elastic · Feb 3, 2025 · f14bc5e · f14bc5e
1 parent 94bd9eb
commit f14bc5e
Show file tree

Hide file tree

Showing 13 changed files with 162 additions and 20 deletions.
diff --git a/...recations/server-internal/src/deprecations/api_deprecations/access/access_deprecations.ts b/...recations/server-internal/src/deprecations/api_deprecations/access/access_deprecations.ts
@@ -33,6 +33,7 @@ export const getIsAccessApiDeprecation = ({
 export const buildApiAccessDeprecationDetails = ({
   apiUsageStats,
   deprecatedApiDetails,
+  docLinks,
 }: BuildApiDeprecationDetailsParams): DomainDeprecationDetails<ApiDeprecationDetails> => {
   const { apiId, apiTotalCalls, totalMarkedAsResolved } = apiUsageStats;
   const { routeVersion, routePath, routeDeprecationOptions, routeMethod } = deprecatedApiDetails;
@@ -43,7 +44,7 @@ export const buildApiAccessDeprecationDetails = ({
     apiId,
     title: getApiDeprecationTitle(deprecatedApiDetails),
     level: deprecationLevel,
-    message: getApiDeprecationMessage(deprecatedApiDetails, apiUsageStats),
+    message: getApiDeprecationMessage(deprecatedApiDetails, apiUsageStats, docLinks),
     documentationUrl: routeDeprecationOptions?.documentationUrl,
     correctiveActions: {
       manualSteps: getApiDeprecationsManualSteps(),

diff --git a/...kages/deprecations/server-internal/src/deprecations/api_deprecations/access/i18n_texts.ts b/...kages/deprecations/server-internal/src/deprecations/api_deprecations/access/i18n_texts.ts
@@ -11,6 +11,8 @@ import { RouterDeprecatedApiDetails } from '@kbn/core-http-server';
 import { CoreDeprecatedApiUsageStats } from '@kbn/core-usage-data-server';
 import { i18n } from '@kbn/i18n';
 import moment from 'moment';
+import { DocLinksServiceSetup } from '@kbn/core-doc-links-server';
+import type { DeprecationDetailsMessage } from '@kbn/core-deprecations-common';
 
 export const getApiDeprecationTitle = (
   details: Pick<RouterDeprecatedApiDetails, 'routePath' | 'routeMethod'>
@@ -31,8 +33,9 @@ export const getApiDeprecationMessage = (
     RouterDeprecatedApiDetails,
     'routePath' | 'routeMethod' | 'routeDeprecationOptions'
   >,
-  apiUsageStats: CoreDeprecatedApiUsageStats
-): string[] => {
+  apiUsageStats: CoreDeprecatedApiUsageStats,
+  docLinks: DocLinksServiceSetup
+): Array<string | DeprecationDetailsMessage> => {
   const { routePath, routeMethod, routeDeprecationOptions } = details;
   const { apiLastCalledAt, apiTotalCalls, markedAsResolvedLastCalledAt, totalMarkedAsResolved } =
     apiUsageStats;
@@ -41,7 +44,7 @@ export const getApiDeprecationMessage = (
   const wasResolvedBefore = totalMarkedAsResolved > 0;
   const routeWithMethod = `${routeMethod.toUpperCase()} ${routePath}`;
 
-  const messages = [
+  const messages: Array<string | DeprecationDetailsMessage> = [
     i18n.translate('core.deprecations.apiAccessDeprecation.apiCallsDetailsMessage', {
       defaultMessage:
         'The API "{routeWithMethod}" has been called {apiTotalCalls} times. The last call was on {apiLastCalledAt}.',
@@ -72,6 +75,16 @@ export const getApiDeprecationMessage = (
         'Internal APIs are meant to be used by Elastic services only. You should not use them. External access to these APIs will be restricted.',
     })
   );
+  messages.push({
+    type: 'markdown',
+    content: i18n.translate('core.deprecations.apiAccessDeprecation.enableDebugLogsMessage', {
+      defaultMessage:
+        'To include information in debug logs about calls to APIs that are internal to Elastic, edit your Kibana configuration as detailed in [the documentation]({enableDeprecationHttpDebugLogsLink}).',
+      values: {
+        enableDeprecationHttpDebugLogsLink: docLinks.links.logging.enableDeprecationHttpDebugLogs,
+      },
+    }),
+  });
 
   if (routeDeprecationOptions?.message) {
     // Surfaces additional deprecation messages passed into the route in UA

diff --git a/...s/server-internal/src/deprecations/api_deprecations/register_api_depercation_info.test.ts b/...s/server-internal/src/deprecations/api_deprecations/register_api_depercation_info.test.ts
@@ -14,18 +14,24 @@ import {
   createGetApiDeprecations,
 } from './register_api_depercation_info';
 import { buildApiDeprecationId } from './api_deprecation_id';
-import { RouterDeprecatedApiDetails } from '@kbn/core-http-server';
+import type {
+  RouterAccessDeprecatedApiDetails,
+  RouterDeprecatedApiDetails,
+} from '@kbn/core-http-server';
 import { httpServiceMock } from '@kbn/core-http-server-mocks';
 import {
   coreUsageDataServiceMock,
   coreUsageStatsClientMock,
 } from '@kbn/core-usage-data-server-mocks';
+import { docLinksServiceMock } from '@kbn/core-doc-links-server-mocks';
 import _ from 'lodash';
+import type { DocLinksServiceSetup } from '@kbn/core-doc-links-server';
 import { CoreDeprecatedApiUsageStats } from '@kbn/core-usage-data-server';
 
 describe('#registerApiDeprecationsInfo', () => {
   const deprecationsFactory = mockDeprecationsFactory.create();
   const deprecationsRegistry = mockDeprecationsRegistry.create();
+  const docLinks: DocLinksServiceSetup = docLinksServiceMock.createSetupContract();
   let usageClientMock: ReturnType<typeof coreUsageStatsClientMock.create>;
   let http: ReturnType<typeof httpServiceMock.createInternalSetupContract>;
   let coreUsageData: ReturnType<typeof coreUsageDataServiceMock.createSetupContract>;
@@ -47,7 +53,7 @@ describe('#registerApiDeprecationsInfo', () => {
 
   it('registers api deprecations', async () => {
     deprecationsFactory.getRegistry.mockReturnValue(deprecationsRegistry);
-    registerApiDeprecationsInfo({ deprecationsFactory, coreUsageData, http });
+    registerApiDeprecationsInfo({ deprecationsFactory, coreUsageData, http, docLinks });
 
     expect(deprecationsFactory.getRegistry).toBeCalledWith('core.api_deprecations');
     expect(deprecationsRegistry.registerDeprecations).toBeCalledTimes(1);
@@ -77,6 +83,19 @@ describe('#registerApiDeprecationsInfo', () => {
         overrides
       );
 
+    const createInternalRouteDetails = (
+      overrides?: Partial<RouterAccessDeprecatedApiDetails>
+    ): RouterAccessDeprecatedApiDetails =>
+      _.merge(
+        {
+          routeAccess: 'internal',
+          routeMethod: 'post',
+          routePath: '/internal/api/',
+          routeVersion: '1.0.0',
+        } as RouterAccessDeprecatedApiDetails,
+        overrides
+      );
+
     const createApiUsageStat = (
       apiId: string,
       overrides?: DeepPartial<CoreDeprecatedApiUsageStats>
@@ -93,7 +112,7 @@ describe('#registerApiDeprecationsInfo', () => {
       );
 
     it('returns removed type deprecated route', async () => {
-      const getDeprecations = createGetApiDeprecations({ coreUsageData, http });
+      const getDeprecations = createGetApiDeprecations({ coreUsageData, http, docLinks });
       const deprecatedRoute = createDeprecatedRouteDetails({
         routePath: '/api/test_removed/',
         routeDeprecationOptions: { reason: { type: 'remove' } },
@@ -129,6 +148,10 @@ describe('#registerApiDeprecationsInfo', () => {
             "level": "critical",
             "message": Array [
               "The API \\"GET /api/test_removed/\\" has been called 13 times. The last call was on Sunday, September 1, 2024 6:06 AM -04:00.",
+              Object {
+                "content": "To include information about deprecated API calls in debug logs, edit your Kibana configuration as detailed in [the documentation](https://www.elastic.co/guide/en/kibana/test-branch/logging-settings.html#enable-http-debug-logs).",
+                "type": "markdown",
+              },
               "This issue has been marked as resolved on Thursday, October 17, 2024 8:06 AM -04:00 but the API has been called 12 times since.",
             ],
             "title": "The \\"GET /api/test_removed/\\" route is removed",
@@ -138,7 +161,7 @@ describe('#registerApiDeprecationsInfo', () => {
     });
 
     it('returns migrated type deprecated route', async () => {
-      const getDeprecations = createGetApiDeprecations({ coreUsageData, http });
+      const getDeprecations = createGetApiDeprecations({ coreUsageData, http, docLinks });
       const deprecatedRoute = createDeprecatedRouteDetails({
         routePath: '/api/test_migrated/',
         routeDeprecationOptions: {
@@ -176,6 +199,10 @@ describe('#registerApiDeprecationsInfo', () => {
             "level": "critical",
             "message": Array [
               "The API \\"GET /api/test_migrated/\\" has been called 13 times. The last call was on Sunday, September 1, 2024 6:06 AM -04:00.",
+              Object {
+                "content": "To include information about deprecated API calls in debug logs, edit your Kibana configuration as detailed in [the documentation](https://www.elastic.co/guide/en/kibana/test-branch/logging-settings.html#enable-http-debug-logs).",
+                "type": "markdown",
+              },
               "This issue has been marked as resolved on Thursday, October 17, 2024 8:06 AM -04:00 but the API has been called 12 times since.",
             ],
             "title": "The \\"GET /api/test_migrated/\\" route is migrated to a different API",
@@ -185,7 +212,7 @@ describe('#registerApiDeprecationsInfo', () => {
     });
 
     it('returns bumped type deprecated route', async () => {
-      const getDeprecations = createGetApiDeprecations({ coreUsageData, http });
+      const getDeprecations = createGetApiDeprecations({ coreUsageData, http, docLinks });
       const deprecatedRoute = createDeprecatedRouteDetails({
         routePath: '/api/test_bumped/',
         routeDeprecationOptions: { reason: { type: 'bump', newApiVersion: '444' } },
@@ -221,6 +248,10 @@ describe('#registerApiDeprecationsInfo', () => {
             "level": "critical",
             "message": Array [
               "The API \\"GET /api/test_bumped/\\" has been called 13 times. The last call was on Sunday, September 1, 2024 6:06 AM -04:00.",
+              Object {
+                "content": "To include information about deprecated API calls in debug logs, edit your Kibana configuration as detailed in [the documentation](https://www.elastic.co/guide/en/kibana/test-branch/logging-settings.html#enable-http-debug-logs).",
+                "type": "markdown",
+              },
               "This issue has been marked as resolved on Thursday, October 17, 2024 8:06 AM -04:00 but the API has been called 12 times since.",
             ],
             "title": "The \\"GET /api/test_bumped/\\" route has a newer version available",
@@ -230,7 +261,7 @@ describe('#registerApiDeprecationsInfo', () => {
     });
 
     it('returns deprecated type deprecated route', async () => {
-      const getDeprecations = createGetApiDeprecations({ coreUsageData, http });
+      const getDeprecations = createGetApiDeprecations({ coreUsageData, http, docLinks });
       const deprecatedRoute = createDeprecatedRouteDetails({
         routePath: '/api/test_deprecated/',
         routeDeprecationOptions: { reason: { type: 'deprecate' }, message: 'additional message' },
@@ -265,6 +296,10 @@ describe('#registerApiDeprecationsInfo', () => {
             "level": "critical",
             "message": Array [
               "The API \\"GET /api/test_deprecated/\\" has been called 13 times. The last call was on Sunday, September 1, 2024 6:06 AM -04:00.",
+              Object {
+                "content": "To include information about deprecated API calls in debug logs, edit your Kibana configuration as detailed in [the documentation](https://www.elastic.co/guide/en/kibana/test-branch/logging-settings.html#enable-http-debug-logs).",
+                "type": "markdown",
+              },
               "This issue has been marked as resolved on Thursday, October 17, 2024 8:06 AM -04:00 but the API has been called 12 times since.",
               "additional message",
             ],
@@ -275,7 +310,7 @@ describe('#registerApiDeprecationsInfo', () => {
     });
 
     it('does not return resolved deprecated route', async () => {
-      const getDeprecations = createGetApiDeprecations({ coreUsageData, http });
+      const getDeprecations = createGetApiDeprecations({ coreUsageData, http, docLinks });
       const deprecatedRoute = createDeprecatedRouteDetails({ routePath: '/api/test_resolved/' });
       http.getRegisteredDeprecatedApis.mockReturnValue([deprecatedRoute]);
       usageClientMock.getDeprecatedApiUsageStats.mockResolvedValue([
@@ -290,7 +325,7 @@ describe('#registerApiDeprecationsInfo', () => {
     });
 
     it('returns never resolved deprecated route', async () => {
-      const getDeprecations = createGetApiDeprecations({ coreUsageData, http });
+      const getDeprecations = createGetApiDeprecations({ coreUsageData, http, docLinks });
       const deprecatedRoute = createDeprecatedRouteDetails({
         routePath: '/api/test_never_resolved/',
       });
@@ -328,15 +363,68 @@ describe('#registerApiDeprecationsInfo', () => {
             "level": "critical",
             "message": Array [
               "The API \\"GET /api/test_never_resolved/\\" has been called 13 times. The last call was on Sunday, September 1, 2024 6:06 AM -04:00.",
+              Object {
+                "content": "To include information about deprecated API calls in debug logs, edit your Kibana configuration as detailed in [the documentation](https://www.elastic.co/guide/en/kibana/test-branch/logging-settings.html#enable-http-debug-logs).",
+                "type": "markdown",
+              },
             ],
             "title": "The \\"GET /api/test_never_resolved/\\" route is removed",
           },
         ]
       `);
     });
 
+    it('returns internal route access deprecation', async () => {
+      const getDeprecations = createGetApiDeprecations({ coreUsageData, http, docLinks });
+      const deprecatedRoute = createInternalRouteDetails({});
+      http.getRegisteredDeprecatedApis.mockReturnValue([deprecatedRoute]);
+      usageClientMock.getDeprecatedApiUsageStats.mockResolvedValue([
+        createApiUsageStat(buildApiDeprecationId(deprecatedRoute), {
+          totalMarkedAsResolved: 0,
+          markedAsResolvedLastCalledAt: undefined,
+        }),
+      ]);
+
+      const deprecations = await getDeprecations();
+      expect(deprecations).toMatchInlineSnapshot(`
+        Array [
+          Object {
+            "apiId": "1.0.0|post|/internal/api",
+            "correctiveActions": Object {
+              "manualSteps": Array [
+                "Identify the origin of these API calls.",
+                "Delete any requests you have that use this API. Check the learn more link for possible alternatives.",
+                "Once you have successfully stopped using this API, mark this issue as resolved. It will no longer appear in the Upgrade Assistant unless another call using this API is detected.",
+              ],
+              "mark_as_resolved_api": Object {
+                "apiTotalCalls": 13,
+                "routeMethod": "post",
+                "routePath": "/internal/api/",
+                "routeVersion": "1.0.0",
+                "timestamp": 2024-10-17T12:06:41.224Z,
+                "totalMarkedAsResolved": 0,
+              },
+            },
+            "deprecationType": "api",
+            "documentationUrl": undefined,
+            "domainId": "core.http.access-deprecations",
+            "level": "warning",
+            "message": Array [
+              "The API \\"POST /internal/api/\\" has been called 13 times. The last call was on Sunday, September 1, 2024 6:06 AM -04:00.",
+              "Internal APIs are meant to be used by Elastic services only. You should not use them. External access to these APIs will be restricted.",
+              Object {
+                "content": "To include information in debug logs about calls to APIs that are internal to Elastic, edit your Kibana configuration as detailed in [the documentation](https://www.elastic.co/guide/en/kibana/test-branch/logging-settings.html#enable-http-debug-logs).",
+                "type": "markdown",
+              },
+            ],
+            "title": "The \\"POST /internal/api/\\" API is internal to Elastic",
+          },
+        ]
+      `);
+    });
+
     it('does not return deprecated routes that have never been called', async () => {
-      const getDeprecations = createGetApiDeprecations({ coreUsageData, http });
+      const getDeprecations = createGetApiDeprecations({ coreUsageData, http, docLinks });
       const deprecatedRoute = createDeprecatedRouteDetails({
         routePath: '/api/test_never_resolved/',
       });

diff --git a/...ations/server-internal/src/deprecations/api_deprecations/register_api_depercation_info.ts b/...ations/server-internal/src/deprecations/api_deprecations/register_api_depercation_info.ts
@@ -15,7 +15,11 @@ import { buildApiDeprecationId } from './api_deprecation_id';
 import type { ApiDeprecationsServiceDeps } from './types';
 
 export const createGetApiDeprecations =
-  ({ http, coreUsageData }: Pick<ApiDeprecationsServiceDeps, 'coreUsageData' | 'http'>) =>
+  ({
+    http,
+    coreUsageData,
+    docLinks,
+  }: Pick<ApiDeprecationsServiceDeps, 'coreUsageData' | 'http' | 'docLinks'>) =>
   async (): Promise<DeprecationsDetails[]> => {
     const usageClient = coreUsageData.getClient();
     const deprecatedApis = http.getRegisteredDeprecatedApis();
@@ -43,6 +47,7 @@ export const createGetApiDeprecations =
             return buildApiRouteDeprecationDetails({
               apiUsageStats,
               deprecatedApiDetails,
+              docLinks,
             });
           }
           // if no access is specified then internal is the default
@@ -51,6 +56,7 @@ export const createGetApiDeprecations =
             return buildApiAccessDeprecationDetails({
               apiUsageStats,
               deprecatedApiDetails,
+              docLinks,
             });
           }
         }
@@ -61,10 +67,11 @@ export const registerApiDeprecationsInfo = ({
   deprecationsFactory,
   http,
   coreUsageData,
+  docLinks,
 }: ApiDeprecationsServiceDeps): void => {
   const deprecationsRegistery = deprecationsFactory.getRegistry('core.api_deprecations');
 
   deprecationsRegistery.registerDeprecations({
-    getDeprecations: createGetApiDeprecations({ http, coreUsageData }),
+    getDeprecations: createGetApiDeprecations({ http, coreUsageData, docLinks }),
   });
 };
diff --git a/...ckages/deprecations/server-internal/src/deprecations/api_deprecations/route/i18n_texts.ts b/...ckages/deprecations/server-internal/src/deprecations/api_deprecations/route/i18n_texts.ts
@@ -9,8 +9,10 @@
 
 import { RouterDeprecatedApiDetails } from '@kbn/core-http-server';
 import { CoreDeprecatedApiUsageStats } from '@kbn/core-usage-data-server';
+import type { DeprecationDetailsMessage } from '@kbn/core-deprecations-common';
 import { i18n } from '@kbn/i18n';
 import moment from 'moment';
+import { DocLinksServiceSetup } from '@kbn/core-doc-links-server';
 
 export const getApiDeprecationTitle = (details: RouterDeprecatedApiDetails) => {
   const { routePath, routeMethod, routeDeprecationOptions } = details;
@@ -37,8 +39,9 @@ export const getApiDeprecationTitle = (details: RouterDeprecatedApiDetails) => {
 
 export const getApiDeprecationMessage = (
   details: RouterDeprecatedApiDetails,
-  apiUsageStats: CoreDeprecatedApiUsageStats
-): string[] => {
+  apiUsageStats: CoreDeprecatedApiUsageStats,
+  docLinks: DocLinksServiceSetup
+): Array<string | DeprecationDetailsMessage> => {
   const { routePath, routeMethod, routeDeprecationOptions } = details;
   if (!routeDeprecationOptions) {
     throw new Error(`Router "deprecated" param is missing for path "${routePath}".`);
@@ -50,7 +53,7 @@ export const getApiDeprecationMessage = (
   const wasResolvedBefore = totalMarkedAsResolved > 0;
   const routeWithMethod = `${routeMethod.toUpperCase()} ${routePath}`;
 
-  const messages = [
+  const messages: Array<string | DeprecationDetailsMessage> = [
     i18n.translate('core.deprecations.apiRouteDeprecation.apiCallsDetailsMessage', {
       defaultMessage:
         'The API "{routeWithMethod}" has been called {apiTotalCalls} times. The last call was on {apiLastCalledAt}.',
@@ -60,6 +63,16 @@ export const getApiDeprecationMessage = (
         apiLastCalledAt: moment(apiLastCalledAt).format('LLLL Z'),
       },
     }),
+    {
+      type: 'markdown',
+      content: i18n.translate('core.deprecations.apiRouteDeprecation.enableDebugLogsMessage', {
+        defaultMessage:
+          'To include information about deprecated API calls in debug logs, edit your Kibana configuration as detailed in [the documentation]({enableDeprecationHttpDebugLogsLink}).',
+        values: {
+          enableDeprecationHttpDebugLogsLink: docLinks.links.logging.enableDeprecationHttpDebugLogs,
+        },
+      }),
+    },
   ];
 
   if (wasResolvedBefore) {