@kbn/core-user-activity-server

This package contains the public types for Core's server-side user activity service.

Technical Reference

Usage

Use trackUserAction to record user actions:

core.userActivity.trackUserAction({
  event: {
    action: 'create_alerting_rule',
    type: 'creation',
    start: new Date().toISOString(),
    end: new Date().toISOString(),
    duration: 250000000, // 250ms in ns
  },
  object: { id: 'production-rule', name: 'My rule', type: 'rule', tags: ['production'] },
});

You can optionally provide a custom message and metadata:

core.userActivity.trackUserAction({
  message: 'User snoozed an alerting rule',
  event: { action: 'snooze_alerting_rule', type: 'change' },
  object: { id: 'rule-456', name: 'CPU usage threshold', type: 'rule', tags: ['production'] },
  metadata: {
    ui_surface: 'rules_table',
    interaction_id: 'snooze_rule_flyout',
  },
});

Registering new actions

Every action must be registered in userActivityActions (src/user_activity_actions.ts). Each entry requires a description, an ownerTeam (GitHub team handle), and a versionAddedAt (Stack version when the action was introduced).

export const userActivityActions = {
  // ... existing actions ...
  create_cases_case: {
    description: 'Create a case',
    ownerTeam: '@elastic/kibana-cases',
    groupName: 'Cases',
    versionAddedAt: '9.3',
  },
} as const satisfies Record<string, UserActivityActionDefinition>;

When an action is removed, move it from userActivityActions to removedUserActivityActions and add versionRemovedAt.

After adding an action, regenerate the docs snippet by running node scripts/generate user-activity-actions-docs. This updates the action list shown in the docs.

Configuration

Configure the service in kibana.yml:

user_activity:
  enabled: true
  appenders:
    # If you don't provide any appender, this is the default we'll use if enabled 
    console:
      type: console
      layout:
        type: json
    # Example: write to file
    file:
      type: file
      fileName: /var/log/kibana/user_activity.log
      layout:
        type: json
  filters:
    - policy: keep
      actions: [create_security_rule]

The appenders option uses the same schema as the core logging service.

Filters

You can optionally configure user_activity.filters to control which event.action values are logged.

For an activity to be logged, its event.action must pass all configured filters:

• policy: keep logs only the actions listed in actions
• policy: drop logs all actions except those listed in actions

If filters is not configured (or empty), all actions are eligible to be logged.

Injected Context

The following context is automatically added to every log entry by Kibana's HTTP middleware:

Log schema

Here's the current schema reference: docs/reference/user-activity.md.

Some of the fields in the schema come from:

• trackUserAction() params (for example message, event.*, object.*, metadata.*)
• Injected context (for example user.*, session.*, client.*, kibana.space.id, and http.request.referrer)
• Fields automatically added by the logging system / JSON layout (for example @timestamp)

Important

If you need to extend this schema, reach out to the Core team (@elastic/kibana-core).

Instrumentation Guidelines

The sections below are aimed at teams deciding what to instrument and how to name it. They complement the technical API reference above and apply to everyone contributing actions to userActivityActions.

1. What to Instrument

The user activity log captures deliberate user decisions, not system behavior or passive navigation. Every event must answer yes to this question: If a user saw this entry in their own activity log, would they recognize it as something they consciously did? Check if an action already exist before instrumenting a new one.

Instrument these

Do not instrument these

2. Event Naming Format

Base Structure: {context}_{noun}_{verb}

All lowercase, snake_case. No camelCase, no hyphens.

For bulk variants, append _bulk to the noun: cases_comment_bulk_delete.

Examples

3. Approved Verb List

Use only verbs from this list. If a new verb is genuinely needed, propose it with the Kibana Core team.

4. Language for Human-Readable Fields

The message field

Format: {Subject} {past-tense verb} {object} [{qualifier}].

Rules:

• Write in third person using "User" as the subject: User created a rule. not You created a rule.
• Use past tense for completed actions: User deleted the dashboard.
• Use present progressive only for in-flight operations logged before the outcome is known: User is creating a connector.
• Include the object name (quoted) and ID when available: User enabled rule "High CPU Alert" (id: abc123).
• Use the product name for objects, not internal type keys: User created a detection rule. not User created a siem.queryRule.
• Use active voice, sentence case, end with a period.

Tense matches outcome

Qualifier patterns

• Object name and ID: "My Rule" (id: abc123)
• Bulk count: User deleted 14 alerts.
• Target system: User pushed case "Login Failure Spike" to ServiceNow (id: case-xyz).
• Failure reason: Reason: Rule contains invalid query syntax.

Other fields

5. Kibana-Specific Examples

Alerting

Cases

Security / Detection

6. Pre-Ship Checklist

• The action is user-initiated, not system-triggered or auto-fired
• The action changes state or represents a high-intent interaction, not a passive read
• Event name follows {context}_{noun}_{verb} in snake_case
• Verb is from the approved list
• Context matches the canonical Kibana plugin name
• message uses correct tense relative to event.outcome
• message includes the object name (quoted) and ID where available
• message uses "User" as the subject in active voice
• No duplicate sub-event is emitted for the same user action
• Bulk operations, append _bulk to the noun