Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 27 additions & 29 deletions src/core/packages/user-activity/server/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -165,28 +165,28 @@ The user activity log captures **deliberate user decisions**, not system behavio

## 2. Event Naming Format

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

| Part | Role | Constraints |
| --- | --- | --- |
| **verb** | The action the user took | Must come from the approved verb list (Section 3) |
| **context** | Kibana feature area | Canonical plugin name, no invented abbreviations |
| **noun** | The object type acted on | Singular, lowercase, matches the product name for the entity |
| **verb** | The action the user took | Must come from the approved verb list (Section 3) |

All lowercase, snake\_case. No camelCase, no hyphens.

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

### Examples

| Event name | Verb | Context | Noun |
| Event name | Context | Noun | Verb |
| --- | --- | --- | --- |
| `create_alerting_rule` | `create` | `alerting` | `rule` |
| `delete_cases_comment` | `delete` | `cases` | `comment` |
| `enable_security_rule` | `enable` | `security` | `rule` |
| `push_cases_case` | `push` | `cases` | `case` |
| `submit_ai_assistant_prompt` | `submit` | `ai_assistant` | `prompt` |
| `install_fleet_integration` | `install` | `fleet` | `integration` |
| `alerting_rule_create` | `alerting` | `rule` | `create` |
| `cases_comment_delete` | `cases` | `comment` | `delete` |
| `security_rule_enable` | `security` | `rule` | `enable` |
| `cases_case_push` | `cases` | `case` | `push` |
| `ai_assistant_prompt_submit` | `ai_assistant` | `prompt` | `submit` |
| `fleet_integration_install` | `fleet` | `integration` | `install` |

## 3. Approved Verb List

Expand Down Expand Up @@ -225,8 +225,8 @@ Use only verbs from this list. If a new verb is genuinely needed, propose it wit
| `submit` | User submits a prompt or form for processing | `send`, `run` (for AI prompts) |
| `run` | User manually triggers an on-demand execution | `execute`, `fire` |
| `schedule` | User schedules a future or recurring action | `automate` |
| `log_in` | User logs in | |
| `log_out` | User logs out | |
| `log_in` | User logs in | `authenticate`,`logged in` |
| `log_out` | User logs out | `unauthenticate`,`logged out` |

## 4. Language for Human-Readable Fields

Expand Down Expand Up @@ -270,44 +270,42 @@ Format: `{Subject} {past-tense verb} {object} [{qualifier}].`
## 5. Kibana-Specific Examples

### Alerting

| Event action | Outcome | `message` |
| --- | --- | --- |
| `create_alerting_rule` | `unknown` | `User is creating a rule.` |
| `create_alerting_rule` | `success` | `User created rule "High CPU Alert" (id: 1a2b3c).` |
| `create_alerting_rule` | `failure` | `User failed to create a rule. Reason: Not authorized.` |
| `snooze_alerting_rule` | `unknown` | `User is snoozing rule "High CPU Alert" (id: 1a2b3c) for 8 hours.` |
| `run_alerting_rule` | `success` | `User ran rule "High CPU Alert" (id: 1a2b3c) on demand.` |
| `alerting_rule_create` | `unknown` | `User is creating a rule.` |
| `alerting_rule_create` | `success` | `User created rule "High CPU Alert" (id: 1a2b3c).` |
| `alerting_rule_create` | `failure` | `User failed to create a rule. Reason: Not authorized.` |
| `alerting_rule_snooze` | `unknown` | `User is snoozing rule "High CPU Alert" (id: 1a2b3c) for 8 hours.` |
| `alerting_rule_run` | `success` | `User ran rule "High CPU Alert" (id: 1a2b3c) on demand.` |

### Cases

| Event action | Outcome | `message` |
| --- | --- | --- |
| `create_cases_case` | `success` | `User created case "Login Failure Spike" (id: case-001).` |
| `update_cases_status` | `success` | `User updated status of case "Login Failure Spike" (id: case-001) to "in-progress".` |
| `push_cases_case` | `unknown` | `User is pushing case "Login Failure Spike" (id: case-001) to ServiceNow.` |
| `close_cases_case` | `success` | `User closed case "Login Failure Spike" (id: case-001).` |
| `cases_case_create` | `success` | `User created case "Login Failure Spike" (id: case-001).` |
| `cases_status_update` | `success` | `User updated status of case "Login Failure Spike" (id: case-001) to "in-progress".` |
| `cases_case_push` | `unknown` | `User is pushing case "Login Failure Spike" (id: case-001) to ServiceNow.` |
| `cases_case_close` | `success` | `User closed case "Login Failure Spike" (id: case-001).` |

### Security / Detection

| Event action | Outcome | `message` |
| --- | --- | --- |
| `create_security_rule` | `success` | `User created detection rule "Potential Credential Dumping" (id: rule-sec-001).` |
| `enable_security_rule` | `unknown` | `User is enabling detection rule "Potential Credential Dumping" (id: rule-sec-001).` |
| `acknowledge_security_alert` | `success` | `User acknowledged alert (id: alert-sec-999) for rule "Potential Credential Dumping".` |
| `security_rule_create` | `success` | `User created detection rule "Potential Credential Dumping" (id: rule-sec-001).` |
| `security_rule_enable` | `unknown` | `User is enabling detection rule "Potential Credential Dumping" (id: rule-sec-001).` |
| `security_alert_acknowledge` | `success` | `User acknowledged alert (id: alert-sec-999) for rule "Potential Credential Dumping".` |




## 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 `{verb}_{context}_{noun}` in snake\_case
- [ ] 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 use the `_bulk` suffix instead of emitting N individual events
- [ ] Bulk operations, append `_bulk` to the noun

Loading