Skip to content

Commit

Permalink
Add ability to granualarly filter events (#364)
Browse files Browse the repository at this point in the history 
* removed posix-api dependency from pom

* added plugin side filtering functionality and unit test cases

* mainly UI changes and event naming changed

* added environment variable tests

* removed config changed event, added conflicting fig checks and tests

* Update src/main/java/org/datadog/jenkins/plugins/datadog/DatadogUtilities.java

Co-authored-by: Sarah Witt <[email protected]>

* Update src/main/java/org/datadog/jenkins/plugins/datadog/DatadogGlobalConfiguration.java

Co-authored-by: Sarah Witt <[email protected]>

* Update src/test/java/org/datadog/jenkins/plugins/datadog/DatadogGlobalConfigurationTest.java

Co-authored-by: Sarah Witt <[email protected]>

* Update src/main/java/org/datadog/jenkins/plugins/datadog/DatadogGlobalConfiguration.java

Co-authored-by: Sarah Witt <[email protected]>

* changed naming of utilities check to send event method

* removed previously deprecated config change getters and setters

* removed event name from class and checking event send method uses name string rather than event

* moved inclusion list creation to datadog utilities and adjusted tests for env variable conflicts

* renamed config check method in global config

* updated documentation

* Remove explicit check for overlapping filters

* Fix tests to assert error message rather than exception

* Update spacing

* Apply suggestions from code review

Co-authored-by: Brett Blue <[email protected]>

* change to shouldSendEvent

* move isTemporarily to base class and still send metrics if event category is excluded

* Update src/main/resources/org/datadog/jenkins/plugins/datadog/DatadogGlobalConfiguration/config.jelly

Co-authored-by: NouemanKHAL <[email protected]>

* Move event names to constants

* Update README.md

Co-authored-by: Brett Blue <[email protected]>

---------

Co-authored-by: Dawit Girma <[email protected]>
Co-authored-by: dawitgirm <[email protected]>
Co-authored-by: Brett Blue <[email protected]>
Co-authored-by: NouemanKHAL <[email protected]>
  • Loading branch information
@sarah-witt @dawitgirm
@brett0000FF @NouemanKHAL
5 people authored Nov 8, 2023
1 parent f206645 commit 77642c6
Show file tree
Hide file tree
Showing 30 changed files with 1,103 additions and 406 deletions.
2 changes: 2 additions & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,5 @@ target/*
nb-configuration.xml
.idea
*.iml
docker-compose.yaml
/.vscode/
49 changes: 31 additions & 18 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -216,6 +216,8 @@ To customize your global configuration, in Jenkins navigate to `Manage Jenkins -
| Global job tags | A comma separated list of regex to match a job and a list of tags to apply to that job. Tags can include environment variables that are defined in the master jenkins instance. **Note**: Tags can reference match groups in the regex using the `$` symbol, for example: `(.*?)_job_(*?)_release, owner:$1, release_env:$2, optional:Tag3` | `DATADOG_JENKINS_PLUGIN_GLOBAL_JOB_TAGS` |
| Send security audit events | Submits the `Security Events Type` of events and metrics (enabled by default). | `DATADOG_JENKINS_PLUGIN_EMIT_SECURITY_EVENTS` |
| Send system events | Submits the `System Events Type` of events and metrics (enabled by default). | `DATADOG_JENKINS_PLUGIN_EMIT_SYSTEM_EVENTS` |
| Include events to send | A comma-separated list of event name strings to send, regardless of the event type being enabled/disabled. | `DATADOG_JENKINS_PLUGIN_INCLUDE_EVENTS` |
| Exclude events to send | A comma-separated list of event name strings not to send, regardless of the event type being enabled/disabled. | `DATADOG_JENKINS_PLUGIN_EXCLUDE_EVENTS` |

### Job customization

Expand Down Expand Up @@ -246,41 +248,52 @@ This plugin is collecting the following [events](#events), [metrics](#metrics),

| Event name | Triggered on | Default tags | Associated RATE metric |
|-----------------|---------------------------|---------------------------------------------------------------------------|-------------------------|
| Build started | `RunListener#onStarted` | `branch`, `event_type`, `jenkins_url`, `job`, `node`, `user_id` | `jenkins.job.started` |
| Build aborted | `RunListener#onDeleted` | `branch`, `event_type`, `jenkins_url`, `job`, `node`, `user_id` | `jenkins.job.aborted` |
| Build completed | `RunListener#onCompleted` | `branch`, `event_type`, `jenkins_url`, `job`, `node`, `result`, `user_id` | `jenkins.job.completed` |
| SCM checkout | `SCMListener#onCheckout` | `branch`, `event_type`, `jenkins_url`, `job`, `node`, `user_id` | `jenkins.scm.checkout` |
| BuildStarted | `RunListener#onStarted` | `branch`, `event_type`, `jenkins_url`, `job`, `node`, `user_id` | `jenkins.job.started` |
| BuildAborted | `RunListener#onDeleted` | `branch`, `event_type`, `jenkins_url`, `job`, `node`, `user_id` | `jenkins.job.aborted` |
| BuildCompleted | `RunListener#onCompleted` | `branch`, `event_type`, `jenkins_url`, `job`, `node`, `result`, `user_id` | `jenkins.job.completed` |
| SCMCheckout | `SCMListener#onCheckout` | `branch`, `event_type`, `jenkins_url`, `job`, `node`, `user_id` | `jenkins.scm.checkout` |

NOTE: `event_type` is always set to `default` for above events and metrics.

#### Systems events type

| Event name | Triggered on | Default tags | Associated RATE metric |
|------------------------------|-----------------------------------------|-------------------------------------------------------------------------|----------------------------------------|
| Computer Online | `ComputerListener#onOnline` | `event_type`, `jenkins_url`, `node_hostname`, `node_name`, `node_label` | `jenkins.computer.online` |
| Computer Offline | `ComputerListener#onOffline` | `event_type`, `jenkins_url`, `node_hostname`, `node_name`, `node_label` | `jenkins.computer.offline` |
| Computer TemporarilyOnline | `ComputerListener#onTemporarilyOnline` | `event_type`, `jenkins_url`, `node_hostname`, `node_name`, `node_label` | `jenkins.computer.temporarily_online` |
| Computer TemporarilyOffline | `ComputerListener#onTemporarilyOffline` | `event_type`, `jenkins_url`, `node_hostname`, `node_name`, `node_label` | `jenkins.computer.temporarily_offline` |
| Computer LaunchFailure | `ComputerListener#onLaunchFailure` | `event_type`, `jenkins_url`, `node_hostname`, `node_name`, `node_label` | `jenkins.computer.launch_failure` |
| Item Created | `ItemListener#onCreated` | `event_type`, `jenkins_url`, `user_id` | `jenkins.item.created` |
| Item Deleted | `ItemListener#onDeleted` | `event_type`, `jenkins_url`, `user_id` | `jenkins.item.deleted` |
| Item Updated | `ItemListener#onUpdated` | `event_type`, `jenkins_url`, `user_id` | `jenkins.item.updated` |
| Item Copied | `ItemListener#onCopied` | `event_type`, `jenkins_url`, `user_id` | `jenkins.item.copied` |
| Item Location Changed | `ItemListener#onLocationChanged` | `event_type`, `jenkins_url`, `user_id` | `jenkins.item.location_changed` |
| Config Changed | `SaveableListener#onChange` | `event_type`, `jenkins_url`, `user_id` | `jenkins.config.changed` |
| ComputerOnline | `ComputerListener#onOnline` | `event_type`, `jenkins_url`, `node_hostname`, `node_name`, `node_label` | `jenkins.computer.online` |
| ComputerOffline | `ComputerListener#onOffline` | `event_type`, `jenkins_url`, `node_hostname`, `node_name`, `node_label` | `jenkins.computer.offline` |
| ComputerTemporarilyOnline | `ComputerListener#onTemporarilyOnline` | `event_type`, `jenkins_url`, `node_hostname`, `node_name`, `node_label` | `jenkins.computer.temporarily_online` |
| ComputerTemporarilyOffline | `ComputerListener#onTemporarilyOffline` | `event_type`, `jenkins_url`, `node_hostname`, `node_name`, `node_label` | `jenkins.computer.temporarily_offline` |
| ComputerLaunchFailure | `ComputerListener#onLaunchFailure` | `event_type`, `jenkins_url`, `node_hostname`, `node_name`, `node_label` | `jenkins.computer.launch_failure` |
| ItemCreated | `ItemListener#onCreated` | `event_type`, `jenkins_url`, `user_id` | `jenkins.item.created` |
| ItemDeleted | `ItemListener#onDeleted` | `event_type`, `jenkins_url`, `user_id` | `jenkins.item.deleted` |
| ItemUpdated | `ItemListener#onUpdated` | `event_type`, `jenkins_url`, `user_id` | `jenkins.item.updated` |
| ItemCopied | `ItemListener#onCopied` | `event_type`, `jenkins_url`, `user_id` | `jenkins.item.copied` |
| ItemLocationChanged | `ItemListener#onLocationChanged` | `event_type`, `jenkins_url`, `user_id` | `jenkins.item.location_changed` |

NOTE: `event_type` is always set to `system` for above events and metrics.

#### Security events type

| Event name | Triggered on | Default tags | Associated RATE metric |
|-----------------------------|-----------------------------------------|--------------------------------------------------|------------------------------|
| User Authenticated | `SecurityListener#authenticated` | `event_type`, `jenkins_url`, `user_id` | `jenkins.user.authenticated` |
| User failed To Authenticate | `SecurityListener#failedToAuthenticate` | `event_type`, `jenkins_url`, `user_id` | `jenkins.user.access_denied` |
| User loggedOut | `SecurityListener#loggedOut` | `event_type`, `jenkins_url`, `user_id` | `jenkins.user.logout` |
| UserAuthenticated | `SecurityListener#authenticated` | `event_type`, `jenkins_url`, `user_id` | `jenkins.user.authenticated` |
| UserFailedToAuthenticate | `SecurityListener#failedToAuthenticate` | `event_type`, `jenkins_url`, `user_id` | `jenkins.user.access_denied` |
| UserLoggedOut | `SecurityListener#loggedOut` | `event_type`, `jenkins_url`, `user_id` | `jenkins.user.logout` |

NOTE: `event_type` is always set to `security` for above events and metrics.

#### Filtering events

This plugin allows you to filter events by the event type as well as the specific event names listed
above. To include/exclude all events of the system or security type:
- **In the UI**: Uncheck the checkboxes for these events.
- **In a groovy script**: Fetch the Datadog global descriptor and call either `d.setEmitSystemEvents()` or `d.setEmitSecurityEvents()`.
- **In the [environment variables](#environment-variables) section**: Set the environment variables for the emitting security or system events.

To get more specific control over what events are sent, three configuration options are provided to allow a comma-separated include/exclude list of strings of event names. The include/exclude list has precedence over filtering by event type. For example, `security` events can be toggled off, but including `UserAuthenticated` takes precedence, so only `UserAuthenticated` events will be sent from the `security` type. In the UI, text boxes are provided for both the included and excluded lists. In a groovy script, the methods `d.setIncludeEvents()` and `d.setExcludeEvents()` accept a comma-separated list of event names as input which is another valid configuration method. Lastly, there are provided [environment variables](#environment-variables) for manually setting included/excluded lists.

NOTE: As mentioned in the [job customization](#job-customization) section, there are job-specific toggles to send `SCMCheckout` events. If the `SCMCheckout` event is excluded globally, this toggle will have no effect.

### Metrics

| Metric Name | Description | Default Tags |
Expand Down
7 changes: 6 additions & 1 deletion pom.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,6 @@
</dependencyManagement>

<dependencies>

<dependency>
<groupId>io.jenkins.plugins</groupId>
<artifactId>jnr-posix-api</artifactId>
Expand All @@ -101,6 +100,12 @@
<version>3.4.0</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>com.github.stefanbirkner</groupId>
<artifactId>system-rules</artifactId>
<version>1.19.0</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>net.bytebuddy</groupId>
<artifactId>byte-buddy-agent</artifactId>
Expand Down
Loading

0 comments on commit 77642c6

Please sign in to comment.