feat(observability): investigate numeric logging verbosity
Chưa có ai nhận issue này.
Đánh giá
- Độ khó
- 5/5
- Thời gian dự kiến
- Hơn một tuần
- Mức phù hợp với người mới
- 30/100
- Loại issue
- Tính năng
- Độ rõ ràng
- Cần làm rõ
- Mức độ hoạt động
- Sôi nổi
- Công nghệ
- rust
- Lĩnh vực
- observability
Hướng nghiên cứu
Bắt đầu với các entry point được liệt kê trong crates/openshell-cli/src/main.rs, crates/openshell-server/src/cli.rs và tracing_setup.rs, cùng crates/openshell-sandbox/src/main.rs, sau đó xem lại các bài kiểm thử logging được tham chiếu và docs/reference/gateway-config.mdx. Issue chỉ được hoàn thành sau khi hợp đồng số, thứ tự ưu tiên, các lớp logging bị ảnh hưởng, phạm vi tương thích và các bài kiểm thử chấp nhận được quyết định trước khi triển khai.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Mô tả
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.
- Ngôn ngữ chính
- Rust
- Star
- 8.7k
- Fork
- 1.3k
- Merge trung bình
- 2 ngày 6 giờ
- Pull request đã merge (30 ngày)
- 297
Hướng dẫn đóng góp
Bắt đầu từ đâu
- Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
- Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
- Fork repository và làm thay đổi trên một nhánh.
- Mở pull request có tham chiếu số hiệu của issue.
Issue khác của NVIDIA/OpenShell
-
area:docs
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 88/100
-
state:triage-needed
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 82/100
-
area:cli state:validated
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 72/100
-
state:triage-needed
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 90/100
-
area:build spike state:review-ready state:stale
Độ khó 2/5 Nửa ngày Mức phù hợp với người mới 68/100
Tất cả issue của NVIDIA/OpenShell
Issue tương tự
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 75/100
-
state:needs triage
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 70/100
zed-industries/zed#64680 · 2 bình luận ·
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 70/100
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 70/100
RustPython/RustPython#8802 ·
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 75/100
TheLarkInn/aipm#2390 ·