Plugin API changes in 7.12

edit

Plugin API changes in 7.12

edit

This page discusses the plugin API changes that you need to be aware of when migrating your application to Kibana 7.12.

Other versions: 7.11 | 7.10 | 7.9 | 7.8

Kibana and Elasticsearch logging config keys unified

The Kibana logging system uses a configuration schema inspired by log4j to provide Elasticsearch compatible format. Several logging configuration keys were renamed to align the naming schema with the Elasticsearch config:

  • *.kind is renamed to ``*.type`
  • file-appender.path to file-appender.fileName
  • logger.xxx.context to logger.xxx.name

Refer to #90764

Camel case now enforced for plugin IDs

Plugin IDs in the kibana.json manifest must be camelCase. This has always been a requirement in the Kibana Platform. Previously, Kibana logged a deprecation warning. Now Kibana refuses to start.

Refer to #90752

Timeout added for "stop" lifecycle

The Kibana plugin system has a concept of asynchronous lifecycles for all the Kibana plugins. The new timeout (30 seconds by default) ensures that the stop lifecycle doesn’t stop the shutdown process for the Kibana server. If a plugin doesn’t complete the stop lifecycle in 30 seconds, Kibana moves to the next plugin.

Refer to #90432

vis_type_timeseries_enhanced plugin removed

All code from x-pack/vis_type_timeseries_enhanced was moved into src/vis_type_timeseries.

Refer to #89274

Field format editors moved from Index Pattern management

The IndexPatternManagement.formatEditors API moved to IndexPatternFieldEditor.formatEditors. The functionality remains the same.

Refer to #89259

fetch$ method added for partial search results

The data plugin search service SearchSource now provides a fetch$ method. In addition to the existing fetch method that returns an Observable, an overall response is returned. This is useful when _async_search is used, and the user needs to handle partial search responses.

Refer to #89211

Explicit typings for request handler context

Whenever Kibana needs access to data saved in Elasticsearch, it should check if the user has access to the data. On the server-side, APIs that require impersonation with an incoming request, are exposed by the context argument of request handler:

const router = core.http.createRouter();
router.get(
  { path: '/api/my-plugin/', validate: … },
  async (context, req, res) => {}
)

Starting with the current version, your plugin should declare an interface of the context parameter explicitly.

Before

declare module 'src/core/server' {
  interface RequestHandlerContext {
    myPlugin?: MyPluginApi;
  }
}

const router = http.createRouter();
http.registerRouteHandlerContext('my-plugin', async (context, req, res) => {...});

After

export interface MyPluginRequestHandlerContext extends RequestHandlerContext {
  myPlugin: MyPluginApi;
}
const router = http.createRouter<MyPluginRequestHandlerContext>();
http.registerRouteHandlerContext<MyPluginRequestHandlerContext, 'my-plugin'>(
  'my-plugin',
  async (context, req, res) => {...}
);

Refer to #88718

Support changed for custom visualizations

You can no longer use a common visualization expression function and a common visualization renderer to retrieve data and render your custom visualization.

To register a custom visualization:

  1. Register a visualization type using the visualizations.createBaseVisualization(config) function, where config is a type of VisTypeDefinition. Refer to the VisTypeDefinition documentation.
  2. Register an expression function definition to handle your custom expression using expressions.registerFunction(functionDefinition), where functionDefinition describes your expression parameters.
  3. Register an explicit renderer for your visualization using expressions.registerRenderer(rendererDefinition), where the rendererDefinition is a type of ExpressionRenderDefinition.

Your visualization is ready to be rendered in Kibana applications, such as Lens, Dashboard, Canvas, and more. Refer to custom visualizations.

Refer to #88317

Search response follows new hits format

When using the data plugin search service search method, you can now provide an additional argument, legacyHitsTotal, in the options. When set to true (the default), the hits.total is returned as a number. When set to false, the hits.total format is returned as-is from the Elasticsearch response.

Refer to #88115

Ops logs added to the KP logging system

We are deprecating the legacy response logs, which were enabled when logging.verbose: true or when using logging.events.ops. The legacy response logs will be removed in 8.0, and replaced with new ops logs that are provided under the metrics.ops context at the debug level.

Before

logging:
  events:
    ops: "*"

After

logging:
  loggers:
    - context: metrics.ops
      appenders: [console]
      level: debug

For more information, check out logging config migration in the logging README.

How to test this:

  1. Add the following logging configuration to your kibana.yml file:

    **kibana.yml or kibana.dev.yml**
    logging:
      events:
        log: ['debug']
        json: false
        verbose: true
    
      appenders:
        console:
          kind: console
          layout:
            kind: pattern
            highlight: true
    
      root:
        appenders: [default]
        level: warn
    
      loggers:
        - context: metrics.metrics
          appenders: [console]
          level: debug
  2. Start Elasticsearch and Kibana.
  3. Observe that the ops metrics are logged out (std out). For example:

    [2021-01-20T22:30:06.974Z][DEBUG][metrics.ops]{"ecs":{"version":"1.7.0"},"kind":"metric","category":["process","host"],"process":{"uptime":640,"memory":{"heap":{"usedInBytes":232472872}},"eventLoopDelay":0.25925004482269287},"host":{"os":{"load":{"1m":8.0625,"5m":7.07470703125,"15m":13.32568359375}}}} memory: 221.7MB uptime: 0:10:40 load: [8.06,7.07,13.33] delay: 0.259

Refer to #88070

Response logs added to the KP logging system

We are deprecating the legacy response logs, which were enabled when logging.verbose: true or when using logging.events.request and logging.events.response. They will be removed in 8.0, and have been replaced with new response logs, which are provided under the http.server.response context at the debug level.

Before

logging:
  events:
    request: "*"
    response: "*"

After

logging:
  loggers:
    - context: http.server.response
      appenders: [console]
      level: debug

For more information, check out logging config migration in the logging README.

Refer to #87939

Telemetry plugins Elasticsearch client migrated to the new client

Support for the legacy Elasticsearch client was removed from the usage collector's fetch context.

Refer to #87356

Dependences between src/plugins/vis_default_editor and src/plugins/visualizations removed

In this change:

  • The ISchemas and Schema interfaces moved from vis_default_editor to the visualizations plugin.
  • The Schemas class moved from vis_default_editor to the visualizations plugin. It’s now a private class, and should not be used outside of the visualizations plugin.
  • The type definition object for visualizations changed.

Before:

  {
       editorConfig: {
         schemas: new Schemas([{schemaObject1, schemasObject2}])
      }
    }

After:

  {
       editorConfig: {
         schemas: [{schemaObject1, schemasObject2}]
      }
    }

Refer to #86988

services.callCluster deprecated in alerts and actions executors

Usage of services.callCluster in the alert and action type executors is deprecated. Use the new services.scopedClusterClient instead.

Refer to #86474