docs: add troubleshooting guide for common plugin issues by S-anskriti · Pull Request #1260 · jenkinsci/opentelemetry-plugin

S-anskriti · 2026-03-19T10:51:08Z

Summary

Adds a new docs/troubleshooting.md file and links it from README.md.

Motivation

Users regularly open issues describing problems that have known
solutions — endpoint failures, auth errors, missing metrics. A
dedicated troubleshooting doc reduces repeated support requests
and helps new users self-diagnose without needing to file an issue.

Changes

Created docs/troubleshooting.md with sections on:
- OTLP endpoint connection failures (ports, TLS, firewall)
- Authentication errors (Bearer tokens, headers format)
- Known issue: metrics stop after config change (references Metrics export stopped after changing the configuration of the Jenkins OpenTelemetry Plugin #424)
- Missing ci.pipeline.* metrics (references Opentelemtry Jenkins metrics ci.pipeline.* are missing #930)
- Enabling FINE log level for debugging
Added a Troubleshooting section to README.md linking to the new guide

Testing

Documentation only — no functional changes.

Note: I am a GSoC 2026 applicant interested in the
Use OpenTelemetry for Jenkins Jobs on ci.jenkins.io
project. This contribution is part of my pre-application community engagement.

Add docs/troubleshooting.md covering: - OTLP endpoint connection failures and port configuration - Authentication errors (Bearer tokens, OTLP headers) - Known workaround for metrics stopping after config change (jenkinsci#424) - Missing ci.pipeline.* metrics and Collector configuration (jenkinsci#930) - How to enable FINE log level for debugging Add Troubleshooting section to README.md linking to the new guide.

S-anskriti · 2026-03-19T10:53:18Z

Hi @shivaylamba and @krisstern,

I'm a GSoC 2026 applicant interested in the "Use OpenTelemetry
for Jenkins Jobs on the "ci.jenkins.io" project. This is my first
contribution to the plugin — would love any feedback on the
content or structure of the troubleshooting guide!

kuisathaverat · 2026-03-19T11:02:10Z

docs/troubleshooting.md

+
+**Symptom:** No traces or metrics appear in your backend. The Jenkins system log shows:
+**Checklist:**
+


the first thing you have to do is check the logs, Jenkins, Collector, and backend

Great point! I'll add log checking as the first step in the checklist
before the other items. Thanks for the review!

kuisathaverat · 2026-03-19T11:02:38Z

docs/troubleshooting.md

+**Symptom:** The Jenkins log shows `UNAUTHENTICATED` or `PERMISSION_DENIED`.
+
+**Checklist:**
+


check the logs too

Understood, will add log checking as step 1 here as well.

kuisathaverat · 2026-03-19T11:04:23Z

docs/troubleshooting.md

+## Metrics stop appearing after a configuration change
+
+**Symptom:** Traces and metrics were working but stopped after updating the
+plugin configuration.
+
+**Known workaround:** Restart the Jenkins controller after changing
+OpenTelemetry settings. The exporter pipeline does not always reinitialise
+without a restart.
+
+Related: [Issue #424](https://github.com/jenkinsci/opentelemetry-plugin/issues/424)
+


This is resolved and the "issue" descrition is vage, I am not sure if it worth to mention it.

Thanks for the clarification! I'll remove this section entirely.
Since the issue has been resolved. I didn't want to reference outdated
workarounds.

kuisathaverat · 2026-03-19T11:07:09Z

docs/troubleshooting.md

+## Missing ci.pipeline.* metrics
+
+**Symptom:** `jenkins.*` metrics arrive correctly but `ci.pipeline.*` metrics
+are absent in your backend.
+
+**Checklist:**
+
+1. Ensure your backend supports OTLP metrics. Prometheus requires the
+   OpenTelemetry Collector with a Prometheus exporter.
+2. Enable `resource_to_telemetry_conversion` on the Collector:
+```yaml
+   exporters:
+     prometheus:
+       endpoint: "0.0.0.0:1234"
+       resource_to_telemetry_conversion:
+         enabled: true
+```
+3. Verify at least one Pipeline build has completed since the plugin was installed.
+
+Related: [Issue #930](https://github.com/jenkinsci/opentelemetry-plugin/issues/930)


no clear what happens and why

You're right, the symptom description is unclear. I'll rewrite it to better explain WHY ci.pipeline.* metrics go missing and what the root cause is. Could you point me to the right context so I can write this accurately?

- Add log checking as first troubleshooting step in OTLP and auth sections - Remove resolved issue jenkinsci#424 reference - Clarify ci.pipeline.* symptom with root cause explanation - Explain why resource_to_telemetry_conversion is needed

S-anskriti · 2026-03-19T11:31:39Z

@kuisathaverat I've pushed an update addressing all your feedback:

Added log checking (Jenkins, Collector, and backend logs) as the
first step in both the OTLP and authentication sections
Removed the Metrics export stopped after changing the configuration of the Jenkins OpenTelemetry Plugin #424 section since the issue is resolved
Rewrote the ci.pipeline.* symptom to explain the root cause —
resource attributes being dropped by backends that require
explicit resource_to_telemetry_conversion configuration
Added the missing error message snippet to the OTLP symptom section

Please let me know if anything else needs adjusting!

S-anskriti · 2026-03-19T12:12:35Z

@kuisathaverat the CI failures appear to be pre-existing and
unrelated to this documentation-only change. Could you confirm
and approve the workflow run so the full CI can execute?

kuisathaverat · 2026-03-22T20:39:14Z

docs/troubleshooting.md

+5. If using the environment variable approach, verify the format:
+
+   OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer YOUR_TOKEN


the authorization is managed by the plugin, this environment variables are used in rare cases

S-anskriti requested a review from a team as a code owner March 19, 2026 10:51

kuisathaverat reviewed Mar 19, 2026

View reviewed changes

kuisathaverat reviewed Mar 22, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add troubleshooting guide for common plugin issues#1260

docs: add troubleshooting guide for common plugin issues#1260
S-anskriti wants to merge 2 commits intojenkinsci:mainfrom
S-anskriti:docs/add-troubleshooting-guide

S-anskriti commented Mar 19, 2026

Uh oh!

S-anskriti commented Mar 19, 2026

Uh oh!

kuisathaverat Mar 19, 2026

Uh oh!

S-anskriti Mar 19, 2026

Uh oh!

kuisathaverat Mar 19, 2026

Uh oh!

S-anskriti Mar 19, 2026

Uh oh!

kuisathaverat Mar 19, 2026

Uh oh!

S-anskriti Mar 19, 2026

Uh oh!

kuisathaverat Mar 19, 2026

Uh oh!

S-anskriti Mar 19, 2026

Uh oh!

S-anskriti commented Mar 19, 2026

Uh oh!

S-anskriti commented Mar 19, 2026

Uh oh!

kuisathaverat Mar 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		Symptom: No traces or metrics appear in your backend. The Jenkins system log shows:
		Checklist:

		Symptom: The Jenkins log shows `UNAUTHENTICATED` or `PERMISSION_DENIED`.

		Checklist:

		5. If using the environment variable approach, verify the format:

		OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer YOUR_TOKEN

Conversation

S-anskriti commented Mar 19, 2026

Summary

Motivation

Changes

Testing

Uh oh!

S-anskriti commented Mar 19, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

S-anskriti commented Mar 19, 2026

Uh oh!

S-anskriti commented Mar 19, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants