Skip to content

Commit 022f0a5

Browse files
cswattcswatt
authored
Merge pull request DataDog#10973 from DataDog/drodriguezhdez/ciapp_jenkins_docs_improvements
[CIAPP] Extend Jenkins documentation for CI Visibility using plugin UI
2 parents c09a0fd + c7cfb86 commit 022f0a5

File tree

2 files changed

+91
-62
lines changed

2 files changed

+91
-62
lines changed

‎content/en/continuous_integration/setup_pipelines/jenkins.md

Lines changed: 91 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -16,59 +16,42 @@ Install the [Datadog Agent][1] on the Jenkins controller instance.
1616

1717
## Install the Datadog Jenkins plugin
1818

19-
Install and enable the [Datadog Jenkins plugin][2] v2.1.1 or newer:
19+
Install and enable the [Datadog Jenkins plugin][2] v3.0.0 or newer:
2020

2121
1. In your Jenkins instance web interface, go to **Manage Jenkins > Manage Plugins**.
2222
2. In the [Update Center][3] on the **Available** tab, search for `Datadog Plugin`.
2323
3. Select the checkbox next to the plugin, and install using one of the two install buttons at the bottom of the screen.
24-
4. To configure the plugin, go to **Manage Jenkins > Configure System**, and find the Datadog Plugin section.
25-
5. In the Datadog section, select the `Datadog Agent` mode.
26-
6. Restart Jenkins to enable the plugin.
27-
28-
When the configuration is correct, the Jenkins log shows lines similar to this after the restart:
29-
30-
{{< code-block lang="text" >}}
31-
INFO datadog.trace.core.CoreTracer#<init>: New instance: DDTracer-62fcf62{ ... }
32-
INFO datadog.trace.core.StatusLogger#logStatus: DATADOG TRACER CONFIGURATION { ... }
33-
{{< /code-block >}}
34-
35-
**Note**: Enabling the collection of traces using the Jenkins plugin is incompatible with running the Java APM tracer as a Java agent when launching Jenkins.
36-
24+
4. To verify that the plugin is installed, search for `Datadog Plugin` on the **Installed** tab.
3725

3826
## Enabling CI Visibility on the plugin
3927

40-
While in beta, the UI to activate CI Visibility is hidden and needs to be manually configured following these steps:
41-
42-
1. Open the file: `$JENKINS_HOME\org.datadog.jenkins.plugins.datadog.DatadogGlobalConfiguration.xml`
43-
44-
2. Add or modify the following lines:
45-
46-
{{< code-block lang="xml" >}}
47-
<reportWith>DSD</reportWith>
48-
<targetHost>localhost</targetHost>
49-
<targetPort>8125</targetPort>
50-
<targetTraceCollectionPort>8126</targetTraceCollectionPort>
51-
<traceServiceName>jenkins</traceServiceName>
52-
<collectBuildTraces>true</collectBuildTraces>
53-
{{< /code-block >}}
54-
55-
3. Restart Jenkins for the changes to take effect.
56-
57-
If the configuration is correct, your Jenkins log should contain the following lines after restarting:
28+
1. In your Jenkins instance web interface, go to **Manage Jenkins > Configure System**.
29+
2. Go to the `Datadog Plugin` section, scrolling down the configuration screen.
30+
3. Select the `Datadog Agent` mode.
31+
4. Configure the `Datadog Agent` host.
32+
5. Configure the `Traces Collection` port. (The default port is `8126` in the Datadog Agent.)
33+
6. Click on `Enable CI Vibisility` checkbox to activate it.
34+
7. Configure your CI Instance name.
35+
8. Check the connectivity with the Datadog Agent.
36+
9. Save your configuration.
37+
10. To verify that CI Visibility is enabled, go to `Jenkins Log` and search for:
5838

5939
{{< code-block lang="text" >}}
60-
INFO datadog.trace.core.CoreTracer#<init>: New instance: DDTracer-62fcf62{ ... }
61-
INFO datadog.trace.core.StatusLogger#logStatus: DATADOG TRACER CONFIGURATION { ... }
40+
Re/Initialize Datadog-Plugin Tracer: hostname = <HOST>, traceCollectionPort = <TRACE_PORT>
41+
DATADOG TRACER CONFIGURATION {...}
6242
{{< /code-block >}}
6343

44+
**Note**: Enabling CI Visibility using the Jenkins plugin is not compatible with running the Java APM tracer as a Java agent when launching Jenkins.
45+
46+
{{< img src="ci/ci-jenkins-plugin-config.png" alt="Datadog Plugin configuration for Jenkins" style="width:100%;">}}
6447

6548
## Enable job log collection on the Agent
6649

6750
Enable log collection in the Agent:
6851

6952
1. Add `logs_enabled: true` to your Agent configuration file `datadog.yaml`, or set the `DD_LOGS_ENABLED=true` environment variable.
7053

71-
2. Create a file at `/etc/datadog-agent/conf.d/jenkins.d/conf.yaml` (for Linux; [check here for other operating systems][4]) with the following contents. Make sure that `service` matches the `traceServiceName` provided earlier:
54+
2. Create a file at `/etc/datadog-agent/conf.d/jenkins.d/conf.yaml` (for Linux; [check here for other operating systems][4]) with the following contents. Make sure that `service` matches the CI Instance name provided earlier:
7255

7356
{{< code-block lang="yaml" >}}
7457
logs:
@@ -84,21 +67,16 @@ With this setup, the Agent listens in port `10518` for logs.
8467

8568
## Enable job log collection in the plugin
8669

87-
Configure the Jenkins plugin to send job logs to the Agent:
88-
89-
1. Open the file: `$JENKINS_HOME\org.datadog.jenkins.plugins.datadog.DatadogGlobalConfiguration.xml`
90-
91-
2. Add or modify the following lines:
92-
93-
{{< code-block lang="xml" >}}
94-
<targetLogCollectionPort>10518</targetLogCollectionPort>
95-
<collectBuildLogs>true</collectBuildLogs>
96-
{{< /code-block >}}
97-
98-
3. Restart Jenkins for the changes to take effect.
99-
100-
**Note**: Do not use the Jenkins web GUI to activate logs collection, as trace collection might be disabled when saving settings using the GUI.
70+
You can correlate your pipeline logs with the traces generated by CI Visibility.
10171

72+
1. In the web interface of your Jenkins instance, go to **Manage Jenkins > Configure System**.
73+
2. Go to the `Datadog Plugin` section, scrolling down the configuration screen.
74+
3. Select the `Datadog Agent` mode.
75+
4. Configure the `Agent` host.
76+
5. Configure the `Log Collection` port.
77+
6. Click on `Enable Log Collection` checkbox to activate it.
78+
7. Check the connectivity with the Datadog Agent.
79+
8. Save your configuration.
10280

10381
## Set the default branch name
10482

@@ -118,6 +96,7 @@ pipeline {
11896
}
11997
}
12098
{{< /code-block >}}
99+
121100
## Customization
122101

123102
### Setting custom tags for your pipelines
@@ -159,28 +138,78 @@ datadog(tags: ["team:backend", "release:canary"]){
159138

160139
You can configure the Jenkins Plugin to send custom tags in all pipeline traces:
161140

162-
1. Open the file `$JENKINS_HOME\org.datadog.jenkins.plugins.datadog.DatadogGlobalConfiguration.xml`.
163-
2. Add or modify the following lines:
164-
165-
{{< code-block lang="xml" >}}
166-
<globalTags>global_tag:global_value,global_tag2:${SOME_ENVVAR},${OTHER_ENVVAR}:global_tagvalue</globalTags>
167-
<globalJobTags>(.*?)_job_(*?)_release:someValue</globalJobTags>
168-
{{< /code-block >}}
169-
170-
**Global tags** (`globalTags`): A comma-separated list of tags to apply to all metrics, traces, events, and service checks. Tags can include environment variables that are defined in the Jenkins controller instance.
141+
1. In the web interface of your Jenkins instance, go to **Manage Jenkins > Configure System**.
142+
2. Go to the `Datadog Plugin` section, scrolling down the configuration screen.
143+
3. Click on the `Advanced` button.
144+
4. Configure the `Global Tags`.
145+
5. Configure the `Global Job Tags`.
146+
6. Save your configuration.
171147

172-
**Global job tags** (`globalJobTags`): 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 Jenkins controller instance. Tags can reference match groups in the regex using the `$` symbol.
148+
**Global tags** (`globalTags`): A comma-separated list of tags to apply to all metrics, traces, events, and service checks. Tags can include environment variables that are defined in the Jenkins controller instance: `global_tag:global_value,global_tag2:${SOME_ENVVAR},${OTHER_ENVVAR}:global_tagvalue`
173149

174-
3. Restart Jenkins for the changes to take effect.
175-
176-
**Note**: Do not use the Jenkins GUI to configure global tags, as trace collection might be disabled when saving settings using the GUI.
150+
**Global job tags** (`globalJobTags`): A comma-separated list of regexes to match a job and a list of tags to apply to that job. Tags can include environment variables that are defined in the Jenkins controller instance. Tags can reference match groups in the regex using the `$` symbol: `(.*?)_job_(*?)_release:someValue`
177151

178152
## Visualize pipeline data in Datadog
179153

180154
Once the integration is successfully configured, both [Pipelines][6] and [Pipeline Executions][7] pages will start populating with data after pipelines finish.
181155

182156
**Note**: The Pipelines page shows data for only the default branch of each repository.
183157

158+
## Troubleshooting
159+
160+
### Enable DEBUG log level for the Datadog Plugin
161+
162+
If you have any issues with the Datadog Plugin, you can set the logs for the plugin in a `DEBUG` log level. Using this level, you are able to check the exception stacktrace if an issue arises.
163+
164+
1. In your Jenkins instance web interface, go to **Manage Jenkins > System log**.
165+
2. Click on `Add new log recorder` button.
166+
3. Type the log recorder name. E.g: **Datadog Plugin Logs**.
167+
4. Add the following loggers to the list:
168+
- Logger: `org.datadog.jenkins.plugins.datadog.clients` -> Log Level `ALL`
169+
- Logger: `org.datadog.jenkins.plugins.datadog.traces` -> Log Level `ALL`
170+
- Logger: `org.datadog.jenkins.plugins.datadog.logs` -> Log Level `ALL`
171+
- Logger: `org.datadog.jenkins.plugins.datadog.model` -> Log Level `ALL`
172+
- Logger: `org.datadog.jenkins.plugins.datadog.listeners` -> Log Level `ALL`
173+
5. Save the configuration.
174+
175+
You may also want to split the loggers into different log recorders.
176+
177+
Once the log recorders are successfully configured, you can check the logs in the `DEBUG` mode by accessing the desired log recorder through **Manage Jenkins > System log**.
178+
179+
If you trigger a Jenkins pipeline, you can search for the message `Send pipeline traces` in the **Datadog Plugin Logs**. This message indicates that the plugin is sending **CI Visibility** data to the **Datadog Agent**.
180+
181+
{{< code-block lang="text" >}}
182+
Send pipeline traces.
183+
...
184+
Send pipeline traces.
185+
...
186+
{{< /code-block >}}
187+
188+
### The Datadog Plugin section does not appear in the Jenkins configuration
189+
190+
If the Datadog Plugin section does not appear in Jenkins configuration section, make sure that the plugin is enabled. To do so:
191+
192+
1. In your Jenkins instance web interface, go to **Manage Jenkins > Manage Plugins**.
193+
2. Search for `Datadog Plugin` in the **Installed** tab.
194+
3. Check that the `Enabled` checkbox is marked.
195+
4. If you enable the plugin here, restart your Jenkins instance using the `/safeRestart` URL path.
196+
197+
### The Plugin Tracer failed to initialized due to APM Java Tracer is used to instrument Jenkins.
198+
199+
If this error message appears in the **Jenkins Log**, make sure that you are not using the APM Java Tracer to instrument your Jenkins instance.
200+
201+
{{< code-block lang="text" >}}
202+
Failed to reinitialize Datadog-Plugin Tracer, Cannot enable traces collection via plugin if the Datadog Java Tracer is being used as javaagent in the Jenkins startup command. This error will not affect your pipelines executions.
203+
{{< /code-block >}}
204+
205+
1. Access your Jenkins controller instance machine using the console.
206+
2. Check the Java startup line for the Jenkins process.
207+
{{< code-block lang="shell" >}}
208+
$> ps -ef | grep jenkins
209+
{{< /code-block >}}
210+
3. Ensure you are not using the APM Java Tracer as `-javaagent`.
211+
212+
**Note**: Enabling CI Visibility using the Jenkins plugin is not compatible with running the Java APM tracer as a Java agent when launching Jenkins.
184213

185214
## Further reading
186215

‎static/images/ci/ci-jenkins-plugin-config.png

224 KB
Loading

0 commit comments

Comments
 (0)