Logging

This page covers what makes a good log message in Kibana. For how to instantiate and call a logger from your plugin, see the logging service tutorial. For security-sensitive actions that need to be recorded separately, see audit logging.

• Do not log sensitive information (personally identifiable information, passwords, api keys, etc.), regardless of the log level. Err on the side of caution. Personally identifiable information is common in user input; for example, dashboard titles, index names and Elasticsearch _search queries.
• Logs should include just enough information to be actionable.
• Use the right log level. The logging service tutorial shows each level in use; as a rule of thumb: trace/debug for developer diagnostics, info for noteworthy lifecycle events (sparingly — see the HTTP API observability guidance), warn for recoverable anomalies, error/fatal for failures that need attention.
• Use ECS format for any additional LogMeta you add to your logging statements.
• Logs are read by customers, a large number of Elastic employees, and Kibana contributors. As such, log messages should use language that is understandable to a wide audience and should avoid disclosing implementation details (unless they're at the debug/trace level).

Operators can configure meta filters on a logger so that records matching selected LogMeta fields are logged at a more verbose level than the logger's nominal level. That only works if call sites pass filterable structured meta.

Recommended conventions:

Do:

logger.error(error, {
  labels: { actionId, actionTypeId, ruleId, spaceId },
  tags: ['action-run-failed'],
});
		

Avoid burying IDs only in the message string or in tags if operators need to filter on them:

// Hard to filter with logging.loggers[].filters
logger.error(`Action '${actionId}' failed: ${error.message}`, {
  tags: [actionTypeId, actionId, 'action-run-failed'],
});
		

See the logging service tutorial for a full operator-facing example.