[thobed]

Resolves AA-693.

Adds an operator-facing runbook for pulling logs from an Access Analyzer install, including pods that are crash-looping or never start.

What's here

• New install/collecting-pod-logs.md: finding failing pods, collecting logs from a running or crash-looping pod, reading Init: and describe output, checking ArgoCD Application status, querying historical logs from ClickHouse, and bundling everything for Netwrix Support
• Links to it from the install index's troubleshooting section

Note

This documents the manual kubectl path only. There's a separate dspm-installer logs/export-logs subcommand in progress on another branch (not yet merged) that would give a more direct primary path — once that lands, this page should get a leading section built around it and demote the manual steps to a fallback.

Test plan

• Checked all internal links resolve
• Read through for accuracy against current namespace/workload names

[github-actions]

Documentation PR Review

Editorial Review

docs/accessanalyzer/26.1/install/collecting-pod-logs.md

• Clarity — Line 7: "These are operator-facing procedures for pulling logs from an Access Analyzer install" describes the document instead of helping the reader, and "operator-facing" is audience-classification language that belongs in a content plan, not on the page. The rest of the install section opens with what the reader does. Suggested fix: "Pull logs from an Access Analyzer install, including pods that are crash-looping or never start, and bundle them for Netwrix Support."

• Completeness — Line 7: The intro uses pod, "namespace", and "ArgoCD Applications" with no grounding. The rest of this section describes Access Analyzer as software that "runs on a single Linux server" (index.md line 6) and never tells the reader it runs as containerized services on an embedded Kubernetes cluster. An administrator arriving here from a failed install has no way to connect "pod" to the product they installed. Suggested fix: add a sentence after the first one — "Access Analyzer runs its services as containers on a k3s Kubernetes cluster that the installer sets up on the host. Each service runs in one or more pods."

• Completeness — Lines 11–26: The Prerequisites section offers two access paths as equivalent ("Run kubectl with sudo, or point KUBECONFIG at the k3s file in a root shell"), but every command from line 30 onward assumes the root shell. A reader who picks the sudo path has no $BUNDLE variable, and sudo kubectl logs ... > "$BUNDLE/pod.log" redirects as the unprivileged user, so the collection commands fail. The Clean Up section's exit confirms the root shell is the intended path. Suggested fix: after the code block, state "The rest of this page assumes the root shell from the preceding commands. If you use sudo per command instead, prefix each kubectl command with sudo and replace $BUNDLE with the directory path."

• Completeness — Lines 80 and 172: These two statements contradict each other. Line 80 says "Databases run as StatefulSets: clickhouse-0, postgres-0, and redis-0," but line 172 gives clickhouse as an example of "the owning Deployment, StatefulSet, or CronJob name." clickhouse-0 is the pod name; clickhouse is the StatefulSet. A reader who takes line 80 at face value will put clickhouse-0 into the ServiceName filter of the ClickHouse query and get no rows back. Suggested fix: "Databases run as StatefulSets named clickhouse, postgres, and redis, each with a single pod: clickhouse-0, postgres-0, and redis-0."

• Completeness — Lines 61, 100, and 151: Three collection commands print to the terminal instead of redirecting into $BUNDLE — the Deployment logs, the init-container logs, and the Job logs. Every other command on the page writes to the bundle directory, so a reader following along will archive at line 190 without the init-container and Job output, which is exactly what the Init: and ArgoCD sections just told them is the useful evidence. Suggested fix: add > "$BUNDLE/<pod-name>-<init-container>.log" and > "$BUNDLE/<job-name>.log" to those commands, matching the pattern used elsewhere.

• Clarity — Line 93: "Use the command without --previous" is abrupt and leaves the reader to infer which command and why. Suggested fix: "If the container hasn't restarted yet, --previous returns previous terminated container ... not found. Run the same command without --previous to read the current instance."

• Structure — Line 95: "Pod Stuck in Init:" sits as an H3 under "Collect Logs From a Crash-Looping Pod," but a pod hung in Init: isn't crash-looping — it never starts, which is the subject of the next H2 (line 105). A reader whose pod shows Init:0/3 will scan to "Describe a Pod That Never Starts" and find a section that lists Pending, ImagePullBackOff, and CreateContainerConfigError but not Init: states. Suggested fix: add a pointer in the never-starts section — "For a pod stuck in an Init: state, see Pod Stuck in Init: — init containers do produce logs."

• Completeness — Line 179: cp /var/log/dspm-installer.log "$BUNDLE/" assumes the default path, but the installer log location is configurable through --log-path / LOG_PATH (see installer-reference.md line 45), and the copy fails silently for anyone who set it. The preflight report at /var/log/dspm-preflight.json, which Support would want for an install that stopped early, isn't collected either. Suggested fix: "The installer writes its own log on the host, and a preflight report alongside it. If the install used --log-path or LOG_PATH, copy that file instead." Then add cp /var/log/dspm-preflight.json "$BUNDLE/" to the code block.

• Structure — Lines 198–205: The Clean Up section shows rm -rf "$BUNDLE" "$BUNDLE.tar.gz" first and only afterward says "Delete the archive only after support confirms receipt." A reader scanning for the cleanup commands copies the destructive line before reaching the condition that governs it, and this is the one step on the page that destroys the evidence they just spent the procedure gathering. Suggested fix: move the constraint above the code block as an admonition — "Delete the archive only after Netwrix Support confirms receipt." Consider :::warning given the page's own warning-block convention at line 194.

• Clarity — Line 202: The comment # leave the root shell opened in Prerequisites reads two ways — exit the shell, or leave it open. The command is exit, so it means the former. Suggested fix: exit # exit the root shell from Prerequisites.

docs/accessanalyzer/26.1/install/index.md

• Structure — Line 28: The new sentence lands under "Scripting or Troubleshooting an Installation," but the page it points to covers ongoing operations well past install time — 30-day historical logs in ClickHouse, ArgoCD Application health, and Job failures that surface after an upgrade. A reader whose pod starts crash-looping weeks later won't look for this under an installation heading. Suggested fix: keep the link, and broaden the heading to "Scripting or Troubleshooting an Installation" → "Scripting, Troubleshooting, and Collecting Logs," or add "during or after an installation" to the new sentence so the scope is clear from the link text.

Summary

11 editorial suggestions across 2 files. Vale and Dale issues are auto-fixed separately.

---

What to do next:

Comment @claude on this PR followed by your instructions to get help:

• @claude fix all issues — fix all editorial issues
• @claude help improve the flow of this document — get writing assistance
• @claude explain the voice issues — understand why something was flagged

You can ask Claude anything about the review or about Netwrix writing standards.

Automated fixes are only available for branches in this repository, not forks.

[github-actions]

Auto-Fix Summary

5 issues fixed, 4 skipped across 2 files

Category	Fixes
OxfordComma (rewrite)	1
Dale: misplaced-modifiers	1
Dale: passive-voice	2
Dale: positional-references	1

Skipped (needs manual review)	Reason

| docs/accessanalyzer/26.1/install/collecting-pod-logs.md:19 — Dale: xy-slop | 'That error means a permissions problem, not a cluster outage' matches the positive-then-negative contrast form, but the negative clause carries real diagnostic information (it preempts a specific misdiagnosis). Every rewrite considered either kept the same structure or weakened the technical claim. |
| docs/accessanalyzer/26.1/install/collecting-pod-logs.md:172 — Dale: xy-slop | 'ServiceName is the owning Deployment ... name, not the pod name' — same pattern as line 19. The trailing negative disambiguates two values an operator would otherwise confuse; removing it loses the warning. |
| docs/accessanalyzer/26.1/install/collecting-pod-logs.md:113 — Dale: positional-references | 'in the Events section at the bottom' describes a physical location within kubectl describe command output, not a cross-reference to other documentation content. The rule targets references to other content. |
| docs/accessanalyzer/26.1/install/collecting-pod-logs.md:202 — Dale: passive-voice | 'leave the root shell opened in Prerequisites' is a reduced relative clause inside a fenced bash code block comment. Editing code block contents risks altering a runnable example, and the construction is grammatical as written. |

Ask @claude on this PR if you'd like an explanation of any fix.