feat(observability): investigate numeric logging verbosity
Nadie ha tomado este issue todavía.
Evaluación
- Dificultad
- 5/5
- Tiempo estimado
- Más de una semana
- Aptitud para principiantes
- 30/100
- Tipo de issue
- Nueva funcionalidad
- Claridad
- Necesita aclaración
- Estado de actividad
- Activo
- Stack tecnológico
- rust
- Área
- observability
Línea de trabajo
Comienza con los puntos de entrada indicados en crates/openshell-cli/src/main.rs, crates/openshell-server/src/cli.rs y tracing_setup.rs, y crates/openshell-sandbox/src/main.rs; después revisa las pruebas de logging referenciadas y docs/reference/gateway-config.mdx. El issue solo estará terminado cuando el contrato numérico, la precedencia, las capas de logging afectadas, el alcance de compatibilidad y las pruebas de aceptación se hayan decidido antes de la implementación.
Escrito por el modelo de indexación a partir del texto del issue.
Descripción
Problem Statement\n\nOpenShell exposes incompatible logging controls: the openshell CLI uses repeated -v, while gateway, sandbox, and credential-driver processes use named log_level values and RUST_LOG directives. Operators who use cloud-native tools such as kubectl expect numeric verbosity, but numeric detail does not map one-to-one to Rust's five severity levels.\n\n## Technical Context\n\nOpenShell already standardizes on the Rust tracing ecosystem. Its structured events and spans are retained through tracing_subscriber EnvFilter. The CLI maps -v counts to warn/info/debug/trace; service executables accept named strings and allow RUST_LOG to override their configured defaults. Sandbox launch specifications propagate a named log_level from the gateway.\n\n## Affected Components\n\n| Component | Key files | Role |\n|---|---|---|\n| CLI | crates/openshell-cli/src/main.rs; src/ssh.rs | Parses -v, installs subscriber, maps verbosity to OpenSSH. |\n| Gateway | crates/openshell-server/src/cli.rs; config_file.rs; tracing_setup.rs | Owns config precedence, OTLP, and in-process driver tracing. |\n| Sandbox | crates/openshell-sandbox/src/main.rs | Configures stderr/file/OCSF/log-push layers. |\n| Sandbox API | crates/openshell-server/src/grpc/{sandbox,validation}.rs; proto/ | Carries and validates SandboxSpec.log_level. |\n| Credential drivers | crates/openshell-driver-{vault,kubernetes-secrets}/src/main.rs | Independently consume OPENSHELL_LOG_LEVEL. |\n| Docs/tests | docs/reference/gateway-config.mdx and logging tests | Document current behaviour. |\n\n## Technical Investigation\n\n### Current behavior\n\n- Cli::verbose is a global Clap ArgAction::Count field at crates/openshell-cli/src/main.rs:467. Startup maps 0/1/2/3+ to warn/info/debug/trace at lines 2401-2418; explicit RUST_LOG wins.\n- The same count controls OpenSSH: ERROR at 0, INFO at 1, DEBUG at 2+ (main.rs:2420-2437; ssh.rs:168-176).\n- Gateway --log-level and OPENSHELL_LOG_LEVEL accept named levels (crates/openshell-server/src/cli.rs:80-82); TOML sets the value only when the CLI argument is defaulted (lines 695-699). Its subscriber uses RUST_LOG first, then configured log_level (lines 520-527).\n- Sandbox --log-level defaults to warn and accepts named levels (crates/openshell-sandbox/src/main.rs:157-159); RUST_LOG also wins (lines 572-573). The file layer has an independent fixed info filter (line 609), while OCSF JSONL and log-push are separate layers.\n- Gateway configuration documents named log_level = info values (docs/reference/gateway-config.mdx:79). Vault and Kubernetes-Secrets credential drivers independently expose the named environment variable.\n\n### Proposed direction\n\nKeep tracing and its native severity levels as the internal event model. Add one documented numeric verbosity contract at OpenShell process boundaries, modelled after Kubernetes -v=N: increasing values enable more normal diagnostic detail while warnings/errors remain visible. Retain RUST_LOG as the highest-precedence expert escape hatch for target-level filtering.\n\nDefine semantics before implementation: whether to support -v=N only, retain repeated -vv as an alias, and whether persistent config/environment variables receive a numeric replacement or accept both forms during a transition. State how a selected value affects stderr, files, OCSF JSONL, streamed logs, OTLP, and OpenSSH child processes.\n\n### Alternatives\n\n1. Keep the current CLI-only count and document it: low risk, but inconsistent controls remain.\n2. Make numeric values simple aliases for warn/info/debug/trace: easy, but not truly kubectl-like.\n3. Define application diagnostic bands (recommended): severity remains meaningful and additional detail is emitted/selected at numeric bands. This requires auditing event placement and layers.\n4. Adopt klog/logr or slog: not recommended because tracing is already used throughout OpenShell for structured spans and OpenTelemetry.\n\n## Scope Assessment\n\n- Complexity: High\n- Confidence: Medium\n- Estimated files to change: 20+ across CLI, gateway, sandbox, proto/config, child drivers, tests, and docs.\n- Issue type: feat\n\n## Risks & Open Questions\n\n- Decide the public numeric contract. Kubernetes uses -v=0 for normal operation and increasing diagnostic verbosity; Rust only has five standard severities.\n- Decide whether all binaries and remote sandbox workloads participate initially or whether the work starts with CLI/gateway.\n- Preserve compatibility for named log_level config, OPENSHELL_LOG_LEVEL, and SandboxSpec.log_level.\n- Ensure sandbox file, OCSF JSONL, and pushed-log layers do not silently diverge from the public numeric setting.\n- Do not invent a Kubernetes-style per-file vmodule initially: RUST_LOG=target=level is idiomatic Rust target filtering.\n- No LSM-sensitive path is involved; this is filtering/configuration only.\n\n## Test Considerations\n\n- Cover -v=N, repeated -vv compatibility if retained, defaults, invalid values, and RUST_LOG precedence.\n- Cover gateway CLI/environment/TOML precedence and sandbox-spec propagation.\n- Integration-test stderr, file, OCSF, and pushed-log filters.\n- Update docs/reference/gateway-config.mdx for any changed TOML field/default and update CLI/sandbox operational docs.\n\n## Disposition Readiness\n\n- State: state:validated\n- Assessment: The codebase and compatibility boundaries are understood well enough for a human accept/decline decision.\n- Missing evidence: None for disposition; the semantic choices above require human direction during planning.\n\n---\nCreated by spike investigation. A human should accept, decline, or roadmap this issue before implementation.
- Lenguaje dominante
- Rust
- Estrellas
- 8.7k
- Forks
- 1.3k
- Merge medio
- 2 d 6 h
- PR fusionados (30 d)
- 297
Guía de contribución
Primeros pasos
- Lee el issue completo y luego la guía de contribución del proyecto.
- Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
- Haz un fork del repositorio y trabaja en una rama.
- Abre un pull request que haga referencia al número del issue.
Más de NVIDIA/OpenShell
-
area:docs
Dificultad 1/5 Menos de una hora Aptitud para principiantes 88/100
-
state:triage-needed
Dificultad 2/5 1-3 horas Aptitud para principiantes 82/100
-
area:cli state:validated
Dificultad 2/5 1-3 horas Aptitud para principiantes 72/100
-
state:triage-needed
Dificultad 1/5 Menos de una hora Aptitud para principiantes 90/100
-
area:build spike state:review-ready state:stale
Dificultad 2/5 Medio día Aptitud para principiantes 68/100
Todos los issues de NVIDIA/OpenShell
Issues similares
-
Dificultad 2/5 1-3 horas Aptitud para principiantes 75/100
-
state:needs triage
Dificultad 2/5 1-3 horas Aptitud para principiantes 70/100
zed-industries/zed#64680 · 2 comentarios ·
-
Dificultad 2/5 1-3 horas Aptitud para principiantes 70/100
-
Dificultad 2/5 1-3 horas Aptitud para principiantes 70/100
RustPython/RustPython#8802 ·
-
Dificultad 2/5 1-3 horas Aptitud para principiantes 75/100
TheLarkInn/aipm#2390 ·