Doctor plugin checks: implement health check classes and documentation
Implement remediation-aware health checks across all Doctor plugin modules (Agent, Attestor, Auth, BinaryAnalysis, Compliance, Crypto, Environment, EvidenceLocker, Notify, Observability, Operations, Policy, Postgres, Release, Scanner, Storage, Vex) and their backing library counterparts (AI, Attestation, Authority, Core, Cryptography, Database, Docker, Integration, Notify, Observability, Security, ServiceGraph, Sources, Verification). Each check now emits structured remediation metadata (severity, category, runbook links, and fix suggestions) consumed by the Doctor dashboard remediation panel. Also adds: - docs/doctor/articles/ knowledge base for check explanations - Advisory AI search seed and allowlist updates for doctor content - Sprint plan for doctor checks documentation Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
68
docs/doctor/articles/observability/log-directory-writable.md
Normal file
68
docs/doctor/articles/observability/log-directory-writable.md
Normal file
@@ -0,0 +1,68 @@
|
||||
---
|
||||
checkId: check.logs.directory.writable
|
||||
plugin: stellaops.doctor.observability
|
||||
severity: fail
|
||||
tags: [observability, logs, quick]
|
||||
---
|
||||
# Log Directory Writable
|
||||
|
||||
## What It Checks
|
||||
Verifies that the log directory exists and is writable. The check:
|
||||
|
||||
- Reads the log path from `Logging:Path` configuration. Falls back to platform defaults: `/var/log/stellaops` on Linux, `%ProgramData%\StellaOps\logs` on Windows.
|
||||
- Verifies the directory exists.
|
||||
- Writes a temporary file to test write access, then deletes it.
|
||||
- Fails if the directory does not exist, is not writable due to permissions, or encounters an I/O error.
|
||||
|
||||
## Why It Matters
|
||||
If the log directory is not writable, application logs are silently lost. Without logs, troubleshooting service failures, debugging policy evaluation issues, and performing security incident investigations becomes impossible. This is a severity-fail check because log loss breaks the auditability guarantee.
|
||||
|
||||
## Common Causes
|
||||
- Log directory not created during installation
|
||||
- Directory was deleted
|
||||
- Configuration points to wrong path
|
||||
- Insufficient permissions or directory owned by different user
|
||||
- Read-only file system
|
||||
- Disk full
|
||||
|
||||
## How to Fix
|
||||
|
||||
### Docker Compose
|
||||
```yaml
|
||||
volumes:
|
||||
- log-data:/var/log/stellaops
|
||||
```
|
||||
|
||||
```bash
|
||||
docker exec <platform-container> mkdir -p /var/log/stellaops
|
||||
```
|
||||
|
||||
### Bare Metal / systemd
|
||||
```bash
|
||||
# Create log directory
|
||||
sudo mkdir -p /var/log/stellaops
|
||||
|
||||
# Set ownership and permissions
|
||||
sudo chown -R stellaops:stellaops /var/log/stellaops
|
||||
sudo chmod 755 /var/log/stellaops
|
||||
```
|
||||
|
||||
### Kubernetes / Helm
|
||||
```yaml
|
||||
logging:
|
||||
path: "/var/log/stellaops"
|
||||
persistence:
|
||||
enabled: true
|
||||
size: 10Gi
|
||||
```
|
||||
|
||||
Or use an `emptyDir` volume for ephemeral log storage with a sidecar shipping logs to an external system.
|
||||
|
||||
## Verification
|
||||
```
|
||||
stella doctor run --check check.logs.directory.writable
|
||||
```
|
||||
|
||||
## Related Checks
|
||||
- `check.logs.rotation.configured` — verifies log rotation is configured
|
||||
- `check.storage.diskspace` — verifies sufficient disk space is available
|
||||
Reference in New Issue
Block a user