refactor: gcp functions tracing doc

[shubham-signoz]

Closes - https://github.com/SigNoz/engineering-pod/issues/3894

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
signoz-web	Ready	Preview, Comment	Mar 25, 2026 5:12am

[claude]

Claude finished @shubham-signoz's task in 3m 31s —— View job

---

Documentation Review Complete

I've completed the review of this GCP Functions tracing documentation refactor. This is a significant improvement—the new version is much more focused, concise, and follows current OpenTelemetry best practices. The refactor reduces 640 lines to 199 while improving clarity and maintainability.

---

Summary of Findings

Critical Issues 🔴

1. Environment variable mismatch (line 40): Using OTEL_EXPORTER_OTLP_TRACES_ENDPOINT but the exporter constructor expects OTEL_EXPORTER_OTLP_ENDPOINT or needs explicit URL parameter. This will likely cause traces to fail silently or use wrong endpoint.

High Priority 🟠

2. Version information needs verification (line 75): The doc claims testing on Feb 13, 2026 (today) with future package versions that may not exist. Needs actual version testing.
3. Missing required Collector section (line 262): Per CONTRIBUTING.md guidelines for Send Data docs, should include optional OTel Collector setup section before troubleshooting.

Medium Priority 🟡

4. Unstable semantic convention (line 102): Uses ATTR_DEPLOYMENT_ENVIRONMENT_NAME from /incubating which may have breaking changes. Should document this caveat.
5. Artificial delay explanation (line 184): The 25ms setTimeout is labeled misleadingly—it's not needed for span visibility, it's simulating work.

Low Priority 🟢

6. Self-hosted endpoint format (line 12): Minor inconsistency in how self-hosted endpoint is shown vs Cloud endpoint.

---

Checklist Against CONTRIBUTING.md

✅ Compliant:

• Frontmatter complete (date, id, title, description, doc_type)
• Self-hosted KeyPointCallout present
• Clear Prerequisites section
• Step-by-step structure with validation
• Troubleshooting section properly collapsed with <ToggleHeading>
• Next steps section with relevant links
• Code snippets explained
• Internal links use absolute https://signoz.io/... format
• Concise, direct language

❌ Needs attention:

• Missing optional Collector setup section (required per guidelines)
• Version info date/versions need verification
• Environment variable configuration issue

⚠️ Should verify:

• All internal links should be manually tested (per guideline line 284)
• Package versions should be tested on actual npm registry

---

Technical Accuracy Verification

I verified the code against official OpenTelemetry sources:

• ✅ NodeSDK configuration follows OTel JS docs
• ✅ GCP resource detector usage matches resource detector patterns
• ⚠️ OTLP endpoint environment variable needs alignment with OTLP spec
• ⚠️ Incubating semantic conventions flagged per OTel JS conventions README

---

Positive Changes 👍

The refactor makes excellent improvements:

• Consolidates Cloud/Self-Host tabs into single Cloud-first flow with self-hosted callout
• Separates concerns with dedicated tracing.js file
• Uses modern OpenTelemetry SDK patterns (NodeSDK, gcpDetector)
• Much clearer, more scannable structure
• Removes outdated screenshots and verbose explanations
• Properly uses doc_type: howto

---

Recommended Actions

Before merging:

1. Fix the environment variable configuration (Critical)
2. Verify and update package versions with actual tested versions
3. Add the optional Collector setup section
4. Consider noting the incubating semantic convention caveat

Labeling:
This is a MODIFICATION of an existing doc (not new), so no add-to-onboarding label needed.

---

Sources

• OTLP Exporter Configuration
• OpenTelemetry JS Node.js Getting Started
• OpenTelemetry JS Semantic Conventions README
• OpenTelemetry JS Resources
• OpenTelemetry Serverless Guide

[makeavish]

@claude review this PR

[claude]

Reviewing PR #2723

• Read repository guidelines (CLAUDE.md, CONTRIBUTING.md)
• Read the changed file and PR diff
• Analyze documentation quality and technical accuracy
• Post review findings

[makeavish]

@claude review this docs pr

[claude]

Claude finished @makeavish's task in 5m 17s —— View job

---

Documentation Review — GCP Functions Tracing Refactor

This is a strong refactor — the doc goes from 704 lines to 298 while becoming significantly more focused, readable, and maintainable. The new version follows modern OTel SDK patterns and aligns well with the CONTRIBUTING.md guidelines. Here are my findings:

---

Correction to Previous Review

The previous review flagged OTEL_EXPORTER_OTLP_TRACES_ENDPOINT as a critical issue. After verifying against the OTLP Exporter spec, the current usage is correct:

• OTEL_EXPORTER_OTLP_TRACES_ENDPOINT (signal-specific) is used as-is — so including /v1/traces is correct.
• OTEL_EXPORTER_OTLP_ENDPOINT (base) auto-appends /v1/traces — so you'd omit the suffix.

The doc correctly uses the signal-specific variable with the full path. ✅

---

Issues Found

🟠 High Priority

1. "Next Steps" links are raw URLs, not descriptive anchor text (lines 295-297)

Per CONTRIBUTING.md (line 277-280): "Use descriptive anchor text that makes the link destination clear. Avoid generic phrases like 'here' and do not paste raw URLs."

Current:

- Correlate traces with logs: https://signoz.io/docs/traces-management/guides/correlate-traces-and-logs/

Should be:

- [Correlate traces with logs](https://signoz.io/docs/traces-management/guides/correlate-traces-and-logs/)

See inline suggestion.

2. Version information date/versions need verification (lines 80-93)

The versions section says "Verified on February 13, 2026" with specific version numbers (e.g., @opentelemetry/sdk-node@0.212.0). These should be confirmed to be actual published versions tested against. If they're projected versions, the date and versions should be updated to reflect actual testing.

3. OTEL_SERVICE_NAME fallback mismatch (line 125 vs line 289)

In tracing.js (line 125), the fallback is:

process.env.OTEL_SERVICE_NAME || `function-${functionId.toLowerCase()}`

But the Troubleshooting section (line 289) says:

"If unset, the fallback name is gcp-cloud-function."

These don't match. The actual fallback in the code is function-a (since FUNCTION_ID defaults to 'A'), not gcp-cloud-function.

See inline suggestion.

🟡 Medium Priority

4. Incubating semantic convention usage not documented (line 118)

const { ATTR_DEPLOYMENT_ENVIRONMENT_NAME } = require('@opentelemetry/semantic-conventions/incubating');

Per the OTel JS semantic conventions README, the /incubating entry point contains unstable attributes that may have breaking changes in minor releases. The code is fine to use, but a brief comment would help users understand this is subject to change.

See inline suggestion.

5. OTEL_EXPORTER_OTLP_HEADERS format may confuse users (line 41)

The env var OTEL_EXPORTER_OTLP_HEADERS=signoz-ingestion-key=<your-ingestion-key> is correct but has two = signs which can be confusing. A brief inline note that this is header-name=header-value format would reduce user confusion, especially since this is a common pain point (referenced in Troubleshooting line 279).

🟢 Low Priority

6. Optional Collector section missing two links (lines 251-269)

The Collector section is present (good!), but compared to the CONTRIBUTING.md template it omits links to Why use the OTel Collector? and the Collector configuration guide.

7. Deploy step lacks --entry-point note (lines 221-224)

The deploy step says "Deploy the function" but doesn't mention the --entry-point entryPoint flag, which matches the function name in functions.http('entryPoint', ...). A brief note or example gcloud command would help.

---

CONTRIBUTING.md Checklist

Requirement	Status	Notes
Frontmatter (date, id, title, description, doc_type)	✅	All present and correct
Self-hosted KeyPointCallout	✅	Present near top
Optional Collector section	✅	Present before Troubleshooting
Cloud-first approach	✅	Uses SigNoz Cloud as default
Code snippets explained	✅	"What this does" section after index.js
Validate section	✅	Present with clear instructions
Troubleshooting (collapsed)	✅	Uses <ToggleHeading> correctly
Next Steps section	⚠️	Present but uses raw URLs instead of markdown links
Internal links use https://signoz.io/...	✅	Correct absolute format
Placeholders explained	✅	All <angle-bracket> placeholders defined
SEO: keywords in title/description/first paragraph	✅	"Cloud Functions", "OpenTelemetry", "traces", "SigNoz"

---

Positive Changes 👍

• Massive simplification: 704 → 298 lines while improving clarity
• Modern OTel patterns: Uses NodeSDK, gcpDetector, resourceFromAttributes
• Clean separation: Dedicated tracing.js file is the recommended OTel pattern
• Eliminates tab duplication: Single Cloud-first flow with self-hosted callout
• Helpful Validate section: The <Admonition> about missing root spans in GCP serverless is a great addition — this is a real user pain point
• Proper doc_type: howto classification

---

Summary

Before merging, fix these:

1. Convert raw URLs to markdown links in "Next Steps" — see suggestion
2. Fix the OTEL_SERVICE_NAME fallback mismatch in Troubleshooting — see suggestion
3. Verify package versions are real and tested

Nice to have:
4. Note the incubating semantic convention caveat — see suggestion
5. Add --entry-point note to the deploy step
6. Add the two missing links to the Collector section

Overall this is a significant improvement. The refactor is well-structured and follows the CONTRIBUTING.md guidelines closely.

---

View job

[makeavish]

@claude review

[claude]

Claude finished @makeavish's task in 2m 29s —— View job

---

Documentation Review — GCP Functions Tracing Refactor

• Read repository guidelines (CONTRIBUTING.md)
• Read the changed file and PR diff
• Analyze documentation quality and technical accuracy
• Check previous review feedback resolution
• Post review findings

---

This is a significant improvement — the doc goes from ~700 lines to ~305 while becoming much more focused and maintainable. The refactor follows modern OTel SDK patterns and aligns well with the CONTRIBUTING.md guidelines.

---

Previous Review Feedback — Resolution Status

Feedback	Status
Raw URLs in Next Steps → use markdown links	✅ Fixed (lines 303-305)
OTEL_SERVICE_NAME fallback mismatch in Troubleshooting	✅ Fixed — misleading fallback text removed (line 297)
Incubating semantic convention caveat	✅ Fixed — code comment added (line 170)
Optional Collector section missing	✅ Added (lines 250-268)
Version info with unverified dates/versions	✅ Removed entirely (cleaner approach)
Collector section missing two reference links	❌ Still missing — see inline suggestion
Deploy step lacks --entry-point note	❌ Still missing — see inline suggestion

---

Remaining Issues

🟡 Medium Priority

1. Collector section missing two reference links (line 266)

Per CONTRIBUTING.md template (lines 486-488), the Collector section should include links to Why use the OTel Collector? and Collector configuration guide. Currently only the "Switch" link is present. See suggestion →

🟢 Low Priority

2. Deploy step is minimal (line 97)

Step 5 says "Deploy the function" without a concrete gcloud command or noting that --entry-point=entryPoint must match functions.http('entryPoint', ...). For a howto doc, a sample deploy command would reduce user friction. See suggestion →

---

CONTRIBUTING.md Checklist

Requirement	Status
Frontmatter (date, id, title, description, doc_type)	✅
Self-hosted KeyPointCallout near top	✅
Cloud-first approach (no tab duplication)	✅
Prerequisites section	✅
Step-by-step structure	✅
Code snippets explained	✅ ("What this does" after index.js)
Placeholders defined below snippets	✅ (lines 49-54)
Validate section	✅ (with helpful <Admonition> about missing root spans)
Optional Collector section before Troubleshooting	✅ (missing 2 links — see above)
Troubleshooting with <ToggleHeading>	✅
Next Steps with descriptive markdown links	✅
Internal links use https://signoz.io/...	✅
SEO keywords in title/description/first paragraph	✅
doc_type: howto matches content	✅

---

Summary

The doc is in good shape. Most feedback from previous reviews has been addressed. Only two minor items remain:

1. Add the two missing reference links to the Collector section (suggestion)
2. Consider adding a sample gcloud deploy command to Step 5 (suggestion)

Neither is a blocker — the doc is a clear improvement over the previous version.

---