Skip to content

OBSDOCS-3693: Complete cleanup from PR #116570 split and fix Configure issues - #117163

Open
johnwilkins wants to merge 17 commits into
openshift:standalone-logging-docs-mainfrom
johnwilkins:OBSDOCS-3693
Open

OBSDOCS-3693: Complete cleanup from PR #116570 split and fix Configure issues#117163
johnwilkins wants to merge 17 commits into
openshift:standalone-logging-docs-mainfrom
johnwilkins:OBSDOCS-3693

Conversation

@johnwilkins

@johnwilkins johnwilkins commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Summary

This PR completes the cleanup from PR #116570, which split configuring-log-forwarding.adoc into 12 focused assemblies but left duplicate content in the original assembly. It also addresses DITA compliance violations and various formatting issues.

Key changes

  1. Fixed 10-link violation in configuring-log-forwarding.adoc (12 → 5 H2 headings)

    • Removed 144 lines of duplicate content left from PR Complete output format documentation (OBSDOCS-3627) #116570 incomplete cleanup
    • The duplicates were: inputs, filters, outputs, pipelines, advanced config, third-party forwarding sections
    • Added cross-reference navigation to the 6 dedicated assemblies

  2. Added consistent cross-reference navigation to Configure assemblies

    • Each assembly now links to parent (configuring-log-forwarding), siblings, and troubleshooting
    • All xrefs include proper anchor IDs for DITA compliance

  3. Fixed Splunk table header in default-splunk-metadata-key-values.adoc

    • Changed from generic header to specific columns matching splunk-hec-output-format.adoc

  4. Fixed CloudWatch backticks in cloudwatch-output-format.adoc

    • Removed backticks from PutLogEvents link text and URL (caused XML parsing errors)

  5. Fixed Vale comment syntax in S3/CloudWatch modules

    • Changed from HTML comments (visible in output) to AsciiDoc comments

  6. Removed only duplicate Additional resources links from modules

    • Kept unique links (Kubernetes label selectors, drop/prune filter examples)
    • Removed only links that duplicated assembly cross-references

Validation

  • ✅ Vale: 0 errors, 2 warnings (acceptable TaskInclude with suppressions)
  • ✅ Heading count: configuring-log-forwarding.adoc now has 5 H2 headings (under 10 limit)
  • ✅ Build: Passes asciidoctor validation

Files changed

  • 14 files modified
  • 68 insertions(+), 179 deletions(-)
  • Net: 111 lines removed

🤖 Generated with Claude Code

@johnwilkins @claude
OBSDOCS-3693: Complete cleanup from PR openshift#116570 split and fix…
8abac3f 
… Configure issues

Addresses incomplete cleanup from PR openshift#116570 and multiple Configure category issues.

Root cause: PR openshift#116570 created separate focused assemblies but left duplicate
content in configuring-log-forwarding.adoc, causing 10-link right-hand nav violation.

Changes:

1. Remove duplicate content from configuring-log-forwarding.adoc
   - Removed 144 lines of duplicate sections (inputs, filters, outputs, pipelines,
     advanced, third-party) that now exist as separate assemblies
   - Added cross-reference navigation to separated assemblies
   - Result: 12 H2 headings → 5 H2 headings (now under 10-link limit)

2. Add cross-reference navigation to Configure assemblies
   - Added Additional resources sections to 6 assemblies: configuring-inputs,
     configuring-filters, configuring-outputs, configuring-pipelines,
     advanced-log-forwarding-configuration, forwarding-to-third-party-systems
   - Removed duplicate cross-references from modules (kept unique links)
   - All xrefs include proper anchor IDs (Vale compliant)

3. Fix Splunk metadata table header
   - Updated default-splunk-metadata-key-values.adoc table header to match
     format from splunk-hec-output-format.adoc
   - Changed from generic columns to specific: Metadata field, Infrastructure
     (journal), Infrastructure/Application (container), Audit logs, Notes

4. Fix CloudWatch backticks in links
   - Removed backticks from PutLogEvents API references in
     cloudwatch-output-format.adoc (line 13 and 81)
   - Prevents XML parsing errors from backticks in link URLs

5. Fix Vale comment syntax
   - Changed HTML comment syntax (<!--vale-->) to AsciiDoc syntax (// vale)
   - Fixes visible comments in forwarding-logs-to-amazon-s3-endpoint.adoc
     and cluster-logging-collector-log-forward-cloudwatch.adoc

Validation:
- Vale: 0 errors, 2 warnings (acceptable TaskInclude warnings with suppressions)
- Heading count: configuring-log-forwarding.adoc now has 5 links (under 10 limit)
- Build: Passes asciidoctor validation

Related: PR openshift#116570, CCSINTL-1948 (JTBD Phase 0)

Signed-off-by: John Wilkins <jowilkin@redhat.com>

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@openshift-ci-robot openshift-ci-robot added the jira/valid-reference Indicates that this PR references a valid Jira ticket of any type. label Aug 3, 2026
@openshift-ci-robot

openshift-ci-robot commented Aug 3, 2026 •
edited by openshift-ci Bot
Loading

Copy link
Copy Markdown

@johnwilkins: This pull request references OBSDOCS-3693 which is a valid jira issue.

Details

In response to this:

Summary

This PR completes the cleanup from PR #116570, which split configuring-log-forwarding.adoc into 12 focused assemblies but left duplicate content in the original assembly. It also addresses DITA compliance violations and various formatting issues.

Key changes

  1. Fixed 10-link violation in configuring-log-forwarding.adoc (12 → 5 H2 headings)
  • Removed 144 lines of duplicate content left from PR Complete output format documentation (OBSDOCS-3627) #116570 incomplete cleanup
  • The duplicates were: inputs, filters, outputs, pipelines, advanced config, third-party forwarding sections
  • Added cross-reference navigation to the 6 dedicated assemblies
  1. Added consistent cross-reference navigation to Configure assemblies
  • Each assembly now links to parent (configuring-log-forwarding), siblings, and troubleshooting
  • All xrefs include proper anchor IDs for DITA compliance
  1. Fixed Splunk table header in default-splunk-metadata-key-values.adoc
  • Changed from generic header to specific columns matching splunk-hec-output-format.adoc
  1. Fixed CloudWatch backticks in cloudwatch-output-format.adoc
  • Removed backticks from PutLogEvents link text and URL (caused XML parsing errors)
  1. Fixed Vale comment syntax in S3/CloudWatch modules
  • Changed from HTML comments (visible in output) to AsciiDoc comments
  1. Removed only duplicate Additional resources links from modules
  • Kept unique links (Kubernetes label selectors, drop/prune filter examples)
  • Removed only links that duplicated assembly cross-references

Validation

  • ✅ Vale: 0 errors, 2 warnings (acceptable TaskInclude with suppressions)
  • ✅ Heading count: configuring-log-forwarding.adoc now has 5 H2 headings (under 10 limit)
  • ✅ Build: Passes asciidoctor validation

Files changed

  • 14 files modified
  • 68 insertions(+), 179 deletions(-)
  • Net: 111 lines removed

🤖 Generated with Claude Code

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

@openshift-ci openshift-ci Bot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Aug 3, 2026
@ocpdocs-previewbot

ocpdocs-previewbot commented Aug 3, 2026 •
edited
Loading

Copy link
Copy Markdown

🤖 Mon Aug 03 19:38:12 - Prow CI generated the docs preview:
https://117163--ocpdocs-pr.netlify.app
Complete list of updated preview URLs: artifacts/updated_preview_urls.txt

johnwilkins and others added 3 commits August 3, 2026 09:55
@johnwilkins @claude
OBSDOCS-3693: Split configuring-the-log-store into 3 DITA-compliant a…
051daf3 
…ssemblies

Split the mega-assembly into logical reading progression to fix DITA's
10-link maximum (H2 + H3 combined).

Created 2 new assemblies:
- about-the-lokistack-log-store.adoc (7 links) - Conceptual understanding
- selecting-loki-storage-provider.adoc (10 links) - Storage provider selection

Revised existing assembly:
- configuring-the-log-store.adoc (5 links) - Deployment procedures

Changes:
- Moved Loki output format, sizing, and workload identity federation to "About" assembly
- Moved storage provider procedures to "Selecting storage provider" assembly
- Removed duplicate tuning content (already exists in tuning-the-log-store.adoc)
- Updated topic map with new assemblies in logical reading order
- Added cross-references for navigation between assemblies

Result: 40 links → 5 links (configuring-the-log-store) ✓
All 3 assemblies now DITA-compliant (≤10 links each)

Signed-off-by: John Wilkins <jowilkin@redhat.com>
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@johnwilkins @claude
OBSDOCS-3693: Fix invalid cross-reference to non-existent troubleshoo…
bae0ca8 
…t-log-store.adoc

Removed cross-reference to troubleshooting/troubleshoot-log-store.adoc
which doesn't exist, causing portal build failure.

Signed-off-by: John Wilkins <jowilkin@redhat.com>
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@johnwilkins @claude
OBSDOCS-3693: Split tuning-the-log-store into 5 DITA-compliant assemb…
cc0297e 
…lies

Split the mega-assembly into focused assemblies to fix DITA's 10-link
maximum (H2 + H3 combined).

Created 4 new Configure assemblies:
- about-log-store-tuning.adoc (7 links) - Prerequisites and dashboards
- tuning-loki-for-performance.adoc (6 links) - Reliability and performance
- tuning-loki-for-scalability.adoc (3 links) - Scalability and HA
- configuring-loki-network-policies.adoc (4 links) - Network security

Created 1 new Logging alerts assembly:
- logging_alerts/configuring-loki-log-based-alerts.adoc (3 links) - Log-based alerts

Changes:
- Removed tuning-the-log-store.adoc from topic map (file still on disk)
- Fixed module title: "Integrating a Loki network policy with external systems"
- Fixed cross-reference to use correct ID: configuring-the-log-store
- Updated topic map with new assemblies in logical reading order
- Added cross-references for navigation between assemblies

Result: 26 links → 23 links across 5 compliant assemblies ✓
All assemblies now DITA-compliant (≤10 links each)

Signed-off-by: John Wilkins <jowilkin@redhat.com>
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@openshift-ci openshift-ci Bot added size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. and removed size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Aug 3, 2026
johnwilkins and others added 9 commits August 3, 2026 11:29
@johnwilkins @claude
OBSDOCS-3693: Update all cross-references to new tuning assemblies
e4426ef 
Fixed references to removed tuning-the-log-store.adoc assembly:
- Generic "Tuning" references → about-log-store-tuning.adoc
- Dashboard references → about-log-store-tuning.adoc#understanding-lokistack-dashboards
- Sizing vs scaling references → tuning-loki-for-scalability.adoc#loki-sizing-vs-component-scaling
- Updated module assembly comment headers to list all new assemblies

Fixed 13 files across installing, configuring, and modules directories.

Signed-off-by: John Wilkins <jowilkin@redhat.com>
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@johnwilkins @claude
OBSDOCS-3693: Remove obsolete tuning-the-log-store.adoc assembly
0109ce2 
Deleted the old mega-assembly that was split into 5 focused assemblies:
- about-log-store-tuning.adoc
- tuning-loki-for-performance.adoc
- tuning-loki-for-scalability.adoc
- configuring-loki-network-policies.adoc
- logging_alerts/configuring-loki-log-based-alerts.adoc

The file was already removed from the topic map and all cross-references
have been updated to point to the new assemblies.

Signed-off-by: John Wilkins <jowilkin@redhat.com>
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@johnwilkins @claude
OBSDOCS-3693: Consolidate performance and scalability into single ass…
a0b40da 
…embly

Merged tuning-loki-for-performance.adoc and tuning-loki-for-scalability.adoc
into tuning-loki-for-performance-and-scalability.adoc (9 links).

Changes:
- Created consolidated assembly with reliability, performance, and scalability topics
- Updated topic map (4 tuning assemblies → 3 tuning assemblies)
- Updated all cross-references to point to consolidated assembly
- Updated module comment headers to reference new assembly
- Deleted separate performance and scalability assemblies

Result: Cleaner structure with 9 links in one assembly instead of 6+3 in two ✓
All assemblies remain DITA-compliant (≤10 links each)

Signed-off-by: John Wilkins <jowilkin@redhat.com>
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@johnwilkins @claude
OBSDOCS-3693: Fix cross-reference ID for configuring-loki-resource-li…
4d4fa84 
…mits

Added missing _{context} suffix to cross-reference anchor ID.
Portal build was failing with "Unknown ID or title" error.

Signed-off-by: John Wilkins <jowilkin@redhat.com>
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@johnwilkins @claude
OBSDOCS-3693: Remove problematic cross-reference to configuring-loki-…
c054ea3 
…resource-limits

Removed cross-reference that was causing portal build failures due to
context variable expansion issues in anchor IDs.

Verified with scripts/prow-smoke-test.sh - All Successful ✓

Signed-off-by: John Wilkins <jowilkin@redhat.com>
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@johnwilkins @claude
OBSDOCS-3693: Split forwarding-to-third-party-systems into 3 DITA-com…
56a0cb7 
…pliant assemblies

Split the mega-assembly into focused assemblies to fix DITA's 10-link
maximum (H2 + H3 combined).

Created 2 new assemblies:
- forwarding-from-pods-and-projects.adoc (6 links) - Source-based filtering
- forwarding-logs-over-http.adoc (8 links) - HTTP-specific implementation

Revised existing assembly:
- forwarding-to-third-party-systems.adoc (5 links) - Generic third-party forwarding

Changes:
- Moved pod/project-specific forwarding (including syslog) to new assembly
- Moved HTTP output and format details to dedicated assembly
- Kept OTLP, Loki, compatibility, and generic concepts in main assembly
- Updated topic map with new assemblies in logical reading order
- Added cross-references for navigation between assemblies

Result: 19 links → 5+6+8=19 links across 3 compliant assemblies ✓
All assemblies now DITA-compliant (≤10 links each)

Verified with scripts/prow-smoke-test.sh - All Successful ✓

Signed-off-by: John Wilkins <jowilkin@redhat.com>
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@johnwilkins @claude
OBSDOCS-3693: Fix CONCEPT module with embedded H2 heading and reuse s…
abca15c 
…ecret procedure

Removed improperly embedded "Creating a Secret" H2 section (lines 87-102)
from cluster-logging-collector-log-forwarding-about.adoc CONCEPT module.

Added loki-create-object-storage-secret-cli.adoc to forwarding-to-third-party-systems
assembly to provide generic secret creation procedure for third-party outputs.

Changes:
- Removed H2 heading from CONCEPT module (violates modular docs structure)
- Reused existing PROCEDURE module for secret creation
- Module title mentions "Loki" but procedure is generic oc create secret
- Assembly context makes it clear it's for third-party forwarding

Verified with scripts/prow-smoke-test.sh - All Successful ✓

Signed-off-by: John Wilkins <jowilkin@redhat.com>
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@johnwilkins @claude
OBSDOCS-3693: Rename module to generic "creating-log-forwarding-secre…
149a2ae 
…t-cli"

Renamed loki-create-object-storage-secret-cli.adoc to creating-log-forwarding-secret-cli.adoc
since the procedure is generic and reused in multiple assemblies.

Changes:
- Renamed module file to reflect generic purpose
- Updated module title: "Creating a secret for log forwarding by using the CLI"
- Updated module ID to creating-log-forwarding-secret-cli_{context}
- Updated abstract to be generic (not Loki-specific)
- Updated module comment header to list both assemblies
- Updated includes in configuring-the-log-store and forwarding-to-third-party-systems

Signed-off-by: John Wilkins <jowilkin@redhat.com>
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@johnwilkins @claude
OBSDOCS-3693: Simplify module title to "Creating a secret by using th…
e5e9958 
…e CLI"

Removed "for log forwarding" from title and abstract - assembly context
already makes the purpose clear.

Signed-off-by: John Wilkins <jowilkin@redhat.com>
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@openshift-ci

openshift-ci Bot commented Aug 3, 2026

Copy link
Copy Markdown

@johnwilkins: all tests passed!

Full PR test history. Your PR dashboard.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

johnwilkins and others added 4 commits August 3, 2026 14:39
@johnwilkins @claude
OBSDOCS-3693: Split cluster-logging-collector into 3 DITA-compliant a…
1441352 
…ssemblies

Split the mega-assembly into focused assemblies with imperative titles
to fix DITA's 10-link maximum (H2 + H3 combined).

Created 2 new assemblies:
- configure-the-collector.adoc (5 links) - Input receivers, rollout, limits
- configure-collector-network-policies.adoc (5 links) - Network policies
- monitor-collector-metrics.adoc (4 links) - Metrics monitoring

Removed old assembly:
- cluster-logging-collector.adoc (17 links) - removed from topic map

Changes:
- Moved input receivers intro text into assembly (preserved context)
- Moved network policies to dedicated assembly
- Moved metrics monitoring to dedicated assembly
- Updated module cross-references to new assemblies
- Removed cross-references to troubleshooting module (will move separately)
- Used imperative tone for titles (Configure, Monitor vs Configuring, Monitoring)
- Updated topic map with new assemblies

Result: 17 links → 5+5+4=14 links across 3 compliant assemblies ✓
All assemblies now DITA-compliant (≤10 links each)

Verified with scripts/prow-smoke-test.sh - All Successful ✓

Signed-off-by: John Wilkins <jowilkin@redhat.com>
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@johnwilkins @claude
Fix bullet list rendering in best practices module
888f507 
Added blank lines after colons before bullet lists to fix rendering.
Without the blank line, AsciiDoc doesn't recognize the bullets and
shows literal asterisks in the rendered output.

Fixed 4 list blocks:
- "Separate pipelines are necessary when:"
- "Pipelines can be combined when:"
- "Use multiple ClusterLogForwarder instances when:"
- "A single ClusterLogForwarder is sufficient when:"

Verified with scripts/prow-smoke-test.sh - All Successful ✓

Signed-off-by: John Wilkins <jowilkin@redhat.com>
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@johnwilkins @claude
Create troubleshoot-the-collector assembly and fix best practices for…
66d27a0 
…matting

Created new troubleshooting assembly:
- troubleshoot-the-collector.adoc - Contains troubleshooting procedures for
  the log collector, including high metrics cardinality diagnostics

Updated best-practices-multitenant-logging module:
- Removed extraneous + continuation markers around "This configuration uses:"
- Removed duplicate Additional resources section (modules shouldn't have them)
- Fixed list formatting to use proper blank line after "This configuration uses:"

Updated cross-references:
- troubleshooting-collector-metrics-cardinality.adoc now references
  monitor-collector-metrics.adoc instead of deleted cluster-logging-collector.adoc
- monitor-collector-metrics.adoc now links to troubleshoot-the-collector assembly

Updated topic map:
- Added "Troubleshoot the collector" after "Troubleshoot the installation"

Result: Troubleshooting content now properly organized in Troubleshoot category
with correct cross-references between configuring and troubleshooting assemblies.

Verified with scripts/prow-smoke-test.sh - All Successful ✓

Signed-off-by: John Wilkins <jowilkin@redhat.com>
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@johnwilkins @claude
Remove Additional resources from modules and fix list continuation ma…
47b346d 
…rkers

Modules should not contain Additional resources sections - only assemblies.
Moved all additional resources links from modules to the assembly's
Additional resources section.

Removed Additional resources from:
- collector-metrics-cardinality-impact.adoc
- configuring-collector-metrics-profiles.adoc
- best-practices-multitenant-logging.adoc (already removed in previous commit)

Consolidated all links in monitor-collector-metrics.adoc assembly:
- Configure the collector
- Troubleshoot the collector
- Configuring inputs
- Configuring filters
- Configuring the monitoring stack
- Metrics collection profiles enhancement
- Prometheus metric and label naming best practices
- Understanding cardinality in Prometheus

Also removed extraneous + list continuation markers from
best-practices-multitenant-logging.adoc that were showing as literal
text in rendered HTML.

Result: Single Additional resources section in assembly, no duplicates ✓

Verified with scripts/prow-smoke-test.sh - All Successful ✓

Signed-off-by: John Wilkins <jowilkin@redhat.com>
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

jira/valid-reference Indicates that this PR references a valid Jira ticket of any type. size/XL Denotes a PR that changes 500-999 lines, ignoring generated files.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@johnwilkins @openshift-ci-robot @ocpdocs-previewbot