Create tracing.adoc

[Rajakavitha1]

added an end to end document for tracing with Otel
addresses: #526

I tested and validated the instructions that are documented in this PR:

[mmattel]

@Rajakavitha1 many thanks for this PR, much appreciated.

We have a deployment example Local Production Setup where the description is located in depl-examples/ubuntu-compose/ubuntu-compose-prod.adoc. This example is based on ocis_full, which is based on compose. Can you migrate your configuration into ocis_full, because then it is automatically embedded in all our examples that are based on it properly. When done and usable, we can think about adding a small note in the description. Most likely via the partial because we have two flavors (local prod and hetzner) which share a lot of content.

[Rajakavitha1]

@Rajakavitha1 many thanks for this PR, much appreciated.

We have a deployment example Local Production Setup where the description is located in depl-examples/ubuntu-compose/ubuntu-compose-prod.adoc. This example is based on ocis_full, which is based on compose. Can you migrate your configuration into ocis_full, because then it is automatically embedded in all our examples that are based on it properly. When done and usable, we can think about adding a small note in the description. Most likely via the partial because we have two flavors (local prod and hetzner) which share a lot of content.

Just incorporated the changes that. you suggested in #1213

[DeepDiver1975]

🤖 Automated review by Claude Code review agent.

Thanks for documenting an end-to-end oCIS → SigNoz tracing workflow — the structure is clear and the step-by-step flow (prerequisites → enable → start → verify → generate traffic) reads well. I do, however, see some blocking issues around file placement / nav wiring and technical accuracy against the upstream ocis_full example that should be resolved before merge.

Overview

• Single new file: modules/ROOT/pages/monitoring/tracing.adoc (233 lines), targeting master.
• Addresses issue #526. Author reports local testing with screenshots.

Blocking issues

1. Wrong module — file is placed in ROOT, not admin

All monitoring documentation lives in the admin component, not ROOT. The existing page is modules/admin/pages/monitoring/prometheus.adoc, and ROOT is just an index shell. Tellingly, prometheus.adoc carries:

:page-aliases: ROOT:monitoring/prometheus.adoc

i.e. monitoring content was deliberately moved out of ROOT into admin, leaving the old ROOT:monitoring/... path only as a redirect alias. This PR puts a new page back into that deprecated location.

Suggested fix: move the file to modules/admin/pages/monitoring/tracing.adoc.

2. Not wired into the navigation

The page is not referenced from any nav.adoc, so it will not appear in the site navigation. The Monitoring section is in modules/admin/partials/nav.adoc (around line 96):

** Monitoring
*** xref:admin:monitoring/prometheus.adoc[Prometheus]

Suggested fix: add a sibling entry, e.g.:

*** xref:admin:monitoring/tracing.adoc[Tracing]

3. Technical accuracy — commands/paths don't match the upstream ocis_full example

I checked owncloud/ocis@master:deployments/examples/ocis_full. Several referenced paths/files do not exist there, so a reader following this guide verbatim will hit errors:

• observability.compose.yml does not exist in ocis_full. Step 3 instructs docker compose -f observability.compose.yml up -d. The example only ships docker-compose.yml (plus monitoring_tracing/*.yml includes).
• monitoring_tracing/signoz/deploy/docker does not exist. Step 1's cd ~/ocis-stable-7.2/.../monitoring_tracing/signoz/deploy/docker points to a directory that isn't in the example. monitoring_tracing/ contains only: empty_dummy.yml, m_collaboration-oo.yml, m_collaboration.yml, monitoring.yml, tracing_env.yml.
• monitoring.yml is not a flat env file. Step 2 says "Edit monitoring.yml and ensure the following tracing configuration is present" with bare keys (OCIS_TRACING_ENABLED: "true", etc.). In reality monitoring.yml is a Compose file (services:/networks:/include:) that extends tracing_env.yml. The tracing env vars actually live in tracing_env.yml, and the upstream default endpoint is OCIS_TRACING_ENDPOINT: jaeger:4317 — not signoz-otel-collector:4317. So the instruction to edit monitoring.yml directly is incorrect for the shipped example.

If this PR documents a custom SigNoz setup you assembled locally (which the screenshots suggest), the guide should either (a) include/contribute the missing SigNoz compose assets to the ocis repo and reference them accurately, or (b) clearly state these files/dirs must be created by the reader and show their contents. As written it reads as if these already exist in ocis_full, which they do not.

Code quality / style (AsciiDoc / Antora)

• Horizontal rule ---: the file uses Markdown-style --- as section separators. In AsciiDoc that is not a thematic break (which is '''); a bare --- line is rendered as literal text / can start an open block. Recommend removing them (Antora pages typically rely on section headings for separation) or use ''' if a rule is truly wanted.
• Missing page header attributes. Compare to prometheus.adoc, which sets :toc: right, :description: ..., and :page-aliases:. Recommend adding at least :toc: and :description: for consistency and SEO/search.
• Placeholder consistency. <name of the container> (step 4) vs <nameof the container> (step 5, missing space). Pick one consistent placeholder, e.g. <ocis-container-name>, and ideally show how to obtain it (docker compose ps).
• Bare URLs as listings. http://localhost:8080 is shown inside ---- literal blocks. Consider inline monospace (http://localhost:8080) or a proper link; a listing block here is heavier than needed.
• No xref links. The page does not cross-reference related docs (e.g. the Prometheus monitoring page or the deployment-examples pages). Adding an xref to the ocis_full example would help readers and is the house style.
• Title length/scope. PR title is "Create tracing.adoc" but the page title is very specific ("...to SigNoz using Docker Compose"). That's fine, but consider a more general H1 (e.g. "Tracing") with SigNoz as a subsection, since the nav label will likely be "Tracing".

Specific suggestions

• Use the example IP convention consistently — the doc uses 192.0.2.24 (TEST-NET-1), which is good for docs; keep that.
• Step 5: nc may not be present in the oCIS container image; consider noting a fallback (e.g. getent hosts alone, or a wget/curl probe) in case nc is unavailable.
• Add a short troubleshooting note: if traces don't appear, check docker logs of the otel-collector and confirm OCIS_TRACING_ENDPOINT matches the collector's service name on the shared ocis-net network.

Potential issues / risks

• Highest risk: because of the wrong module path + missing nav entry, this page will not be discoverable on the built site even if merged.
• Reader-breaking: the non-existent observability.compose.yml and signoz/deploy/docker path, plus editing monitoring.yml directly, mean the documented happy path cannot be followed against the current upstream example. This is the most important correctness item to reconcile.
• Version pinning: instructions hard-code ~/ocis-stable-7.2/.... Antora has attributes for versioned paths (see antora.yml, e.g. ocis_repo_url_stable). Hard-coded 7.2 will rot; consider attribute-based or version-neutral paths.

Net: solid first draft of a genuinely useful guide. Please (1) move to modules/admin/pages/monitoring/tracing.adoc, (2) add the nav entry, (3) reconcile the SigNoz commands/paths with what actually ships in ocis_full (or contribute the missing assets), and (4) align AsciiDoc syntax/header attributes with prometheus.adoc.