WDP Part 1: Severity Field Specification
Part 1 of the Waddling Diagnostic Protocol (WDP): the Severity field. The severity field is a single character that indicates the urgency, impact, and type of a diagnostic code.
Abstract#
This document specifies Part 1 of the Waddling Diagnostic Protocol (WDP): the Severity field. The severity field is a single character that indicates the urgency, impact, and type of a diagnostic code. WDP defines nine severity levels, each with distinct semantics, priorities, and blocking characteristics.
Specification Navigation: See STRUCTURE.md for an overview of all WDP specification parts.
Conformance
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
1. Introduction#
1.1 Purpose
The severity field is the first part of a WDP error code. It provides an immediate indication of:
- Urgency: How quickly must this be addressed?
- Impact: What is the consequence of this condition?
- Type: Is this an error, warning, success, or informational message?
- Blocking: Does this condition prevent further execution?
1.2 Position in Error Code
Complete WDP Structure:
Severity.Component.Primary.Sequence -> CompactID
^ ^ ^ ^ ^
Part 1 Part 2 Part 3 Part 4 Part 5This Document Focus:
Severity.Component.Primary.Sequence -> CompactID
^^^^^^^^
Part 1: Single character indicating urgency (THIS DOCUMENT)Example: E.Auth.Token.001 - The E indicates an Error severity.
1.3 Design Goals
- Single character: Compact and easily recognizable
- Intuitive codes: Letters suggest meaning (E=Error, W=Warning, etc.)
- Comprehensive: Cover all diagnostic needs (errors, warnings, successes, traces)
- Prioritizable: Clear ordering by urgency
- Universal: Same semantics across all languages and platforms
2. Severity Levels#
WDP defines nine severity levels, each represented by a single uppercase ASCII letter.
2.1 Complete Severity Table
| Code | Name | Priority | Blocking | Tone | Description |
|---|---|---|---|---|---|
| E | Error | 8 | Yes | Negative | Invalid input, logic errors, failures that prevent operation |
| B | Blocked | 7 | Yes | Negative | Operation blocked by external condition (deadlock, I/O wait) |
| C | Critical | 6 | No | Negative | Severe conditions requiring immediate attention (data corruption) |
| W | Warning | 5 | No | Negative | Potentially problematic situations (deprecated API, edge cases) |
| H | Help | 4 | No | Neutral | Helpful suggestions, tips, or guidance |
| S | Success | 3 | No | Positive | Operation completed successfully |
| K | Completed | 2 | No | Positive | Task or phase finished (K for "complete" to avoid S conflict) |
| I | Info | 1 | No | Neutral | Informational events, milestones, status updates |
| T | Trace | 0 | No | Neutral | Execution traces, probes, timing measurements |
2.2 Severity Definitions
E - Error (Priority 8)
Blocking: Yes
Tone: Negative
Definition: An error indicates that an operation has failed and cannot continue. This severity is used for invalid inputs, logic errors, and any condition that prevents normal execution.
When to use:
- Required parameter is missing
- Invalid data format or type
- Business logic violation
- Resource access denied
- Operation failed unexpectedly
Examples:
E.Auth.Token.001 - Missing authentication token
E.Parser.Syntax.003 - Invalid syntax in input
E.Database.Query.FAILED - Database query failed
E.FileSystem.File.021 - File not foundB - Blocked (Priority 7)
Blocking: Yes
Tone: Negative
Definition: A blocked condition indicates that an operation cannot proceed due to an external constraint, such as waiting for a resource, deadlock, or I/O operation timeout.
When to use:
- Waiting for mutex/lock
- I/O operation blocked or timed out
- Deadlock detected
- Network connection unavailable
- Resource temporarily unavailable
Examples:
B.Thread.Mutex.024 - Waiting for mutex lock
B.Io.Wait.TIMEOUT - I/O operation blocked/timeout
B.Network.Connection.027 - Network connection unavailable
B.Database.Lock.024 - Database row locked by another transactionDifference from Error: Blocked conditions are often temporary and may resolve without intervention (e.g., lock released, network restored). Errors typically require user or developer action.
C - Critical (Priority 6)
Blocking: No
Tone: Negative
Definition: A critical condition indicates a severe problem that requires immediate attention, but does not necessarily block execution. Examples include data corruption, resource exhaustion, or system instability.
When to use:
- Data corruption detected
- Resource nearly exhausted (disk, memory)
- System stability threatened
- Security breach detected
- Irreversible failure occurred
Examples:
C.Data.Integrity.025 - Data corruption detected
C.Memory.Exhausted.026 - Out of memory
C.Disk.Full.026 - Disk space exhausted
C.Security.Breach.008 - Security violation detectedDifference from Error: Critical conditions may allow continued execution (possibly in degraded mode) but indicate serious problems requiring immediate operator attention.
W - Warning (Priority 5)
Blocking: No
Tone: Negative
Definition: A warning indicates a potentially problematic situation that does not prevent operation but may lead to errors or unexpected behavior. Warnings often indicate deprecated features, configuration issues, or edge cases.
When to use:
- Deprecated API or feature used
- Sub-optimal configuration
- Edge case encountered
- Performance degradation
- Recoverable error occurred
Examples:
W.Api.Deprecated.010 - API method deprecated
W.Cache.Miss.018 - Cache miss (degraded performance)
W.Config.Default.USED - Using default configuration
W.Parser.Ambiguous.003 - Ambiguous syntax (guessing interpretation)H - Help (Priority 4)
Blocking: No
Tone: Neutral
Definition: Help severity provides suggestions, tips, or guidance to users or developers. This is not an error or warning, but rather helpful information.
When to use:
- Usage suggestions
- Performance optimization tips
- Configuration recommendations
- Best practice guidance
- Tutorial or learning content
Examples:
H.Usage.Tip.SUGGESTION - Helpful usage suggestion
H.Perf.Optimization.001 - Performance optimization tip
H.Config.Recommended.001 - Recommended configuration
H.Security.BestPractice - Security best practiceS - Success (Priority 3)
Blocking: No
Tone: Positive
Definition: Success severity indicates that an operation completed successfully. This provides explicit positive feedback, especially useful for operations where silence might be ambiguous.
When to use:
- Authentication/login succeeded
- File uploaded successfully
- Transaction committed
- Validation passed
- Operation explicitly succeeded
Examples:
S.Auth.Login.SUCCESS - Login successful
S.Upload.Complete.999 - File upload finished successfully
S.Transaction.Commit.999 - Transaction committed
S.Validation.Pass.999 - Validation passedK - Completed (Priority 2)
Blocking: No
Tone: Positive
Definition: Completed severity indicates that a long-running task or phase has finished. The "K" avoids conflict with "C" (Critical) and "S" (Success).
When to use:
- Build completed
- Migration finished
- Backup completed
- Batch processing finished
- Long-running task done
Examples:
K.Build.Done.999 - Build completed
K.Migration.Finished.999 - Database migration finished
K.Backup.Complete.999 - Backup completed
K.BatchJob.Done.999 - Batch processing completedDifference from Success: Success is for individual operations; Completed is for multi-step tasks or phases.
I - Info (Priority 1)
Blocking: No
Tone: Neutral
Definition: Informational severity provides status updates, milestones, or general information about system state or operations.
When to use:
- Server starting/stopping
- Request received
- Configuration loaded
- Status updates
- Statistics or metrics
Examples:
I.Server.Startup.001 - Server starting up
I.Request.Received.001 - HTTP request received
I.Cache.Stats.001 - Cache statistics
I.Config.Loaded.001 - Configuration loadedT - Trace (Priority 0)
Blocking: No
Tone: Neutral
Definition: Trace severity is used for detailed execution traces, debugging information, profiling, and performance measurements. Typically enabled only during development or debugging.
When to use:
- Function entry/exit (profiling)
- Timer checkpoints
- Execution probes
- Variable state dumps
- Performance measurements
Examples:
T.Function.Entry.001 - Function entered (profiling)
T.Timer.Start.001 - Timer started
T.Probe.Checkpoint.001 - Execution checkpoint
T.Variable.Dump.001 - Variable state dump3. Field Specification#
3.1 Format
Type: Single uppercase ASCII letter
Character Set: [EWCBSHKIT]
Required: YES (mandatory field)
Position: First field (leftmost)
Length: Exactly 1 character
3.2 Validation Rules
Valid severities:
E, W, C, B, S, K, I, T, HValidation regex:
^[EWCBSHKIT]$Case-sensitive: Must be uppercase. Lowercase letters are invalid.
Valid examples:
E // valid
W // valid
S // validInvalid examples:
e // invalid: lowercase not allowed
X // invalid: not a defined severity
ER // invalid: multiple characters not allowed4. Priority System#
4.1 Purpose
Each severity level has an associated priority value (0-8, higher = more urgent). Priorities enable:
- Sorting errors by importance
- Filtering by minimum priority threshold
- Alert routing based on urgency
- Log level configuration
4.2 Priority Values
| Severity | Priority | Interpretation |
|---|---|---|
| E | 8 | Highest priority - immediate attention |
| B | 7 | High priority - blocked execution |
| C | 6 | High priority - critical condition |
| W | 5 | Medium priority - warning |
| H | 4 | Low-medium priority - helpful info |
| S | 3 | Low priority - success confirmation |
| K | 2 | Low priority - completion notice |
| I | 1 | Very low priority - informational |
| T | 0 | Lowest priority - trace/debug |
4.3 Priority Ordering
Complete ordering (lowest to highest):
T(0) < I(1) < K(2) < S(3) < H(4) < W(5) < C(6) < B(7) < E(8)4.4 Use Cases
Filtering by priority:
Show only priority >= 5: W, C, B, E (warnings and above)
Show only priority >= 7: B, E (blocking conditions only)
Show only priority >= 1: All except TraceAlert routing:
Priority 8 (E): Page on-call engineer
Priority 7 (B): Alert operations team
Priority 6 (C): Email alerts
Priority 5 (W): Log aggregation
Priority 0-4: Standard logging5. Blocking Semantics#
5.1 Blocking vs Non-Blocking
Blocking severities (E, B):
- Indicate the operation cannot proceed
- Execution stops or waits
- Require intervention (user, system, or time)
- Return value: typically an error result or exception
Non-blocking severities (C, W, H, S, K, I, T):
- Operation can continue (possibly degraded)
- Provide information, warnings, or confirmations
- Do not halt execution
- Return value: typically success or informational
5.2 Examples
Blocking:
E.Auth.Token.001 → Cannot proceed without token
B.Thread.Mutex.024 → Waiting for lock release
E.Database.Connection.021 → Cannot query without connectionNon-blocking:
W.Api.Deprecated.010 → Can proceed, but API will be removed
C.Memory.Low.026 → System continues but at risk
S.Auth.Login.SUCCESS → Operation succeeded, continue6. Classification#
6.1 Overview
WDP severities are classified by tone - the nature or character of the message:
6.2 Negative Tone (E, B, C, W)
Indicates: Problems or concerns
Priority: 5-8
- E (Error): Operation failed
- B (Blocked): Operation blocked
- C (Critical): Severe condition
- W (Warning): Potential problem
6.3 Positive Tone (S, K)
Indicates: Successful outcomes
Priority: 2-3
- S (Success): Operation succeeded
- K (Completed): Task finished
6.4 Neutral Tone (H, I, T)
Indicates: Informational or advisory
Priority: 0-4
- H (Help): Helpful information
- I (Info): Status update
- T (Trace): Debug trace
6.5 Use in Analysis
Dashboard "Health" score:
Negative tone count: High → System unhealthy
Positive tone count: High → System healthy
Neutral tone: Informational onlyAlerting:
Negative tone (E, B, C, W): Trigger alerts
Positive tone (S, K): Optional notifications
Neutral tone (H, I, T): Logging only7. Use Cases by Severity#
7.1 Error (E) - Examples
E.Auth.Token.001 - Missing authentication token
E.Auth.Token.003 - Invalid token format
E.Auth.Permission.008 - Permission denied
E.Parser.Syntax.003 - Invalid syntax in input
E.Parser.Token.001 - Unexpected token
E.Database.Query.FAILED - Database query failed
E.Database.Connection.021 - Database not found
E.FileSystem.File.021 - File not found
E.FileSystem.File.008 - Permission denied
E.Network.Connection.028 - Host unreachable
E.Network.Timeout.017 - Connection timeout7.2 Blocked (B) - Examples
B.Thread.Mutex.024 - Waiting for mutex lock
B.Thread.Deadlock.024 - Deadlock detected
B.Io.Wait.TIMEOUT - I/O operation blocked/timeout
B.Io.Read.BLOCKED - Read operation blocked
B.Network.Connection.027 - Network connection unavailable
B.Network.Retry.WAITING - Waiting for retry
B.Database.Lock.024 - Database row locked
B.Database.Waiting.024 - Waiting for transaction7.3 Critical (C) - Examples
C.Data.Integrity.025 - Data corruption detected
C.Data.Checksum.025 - Checksum verification failed
C.Memory.Exhausted.026 - Out of memory
C.Memory.Leak.026 - Memory leak detected
C.Disk.Full.026 - Disk space exhausted
C.Disk.Failing.025 - Disk hardware failure detected
C.Security.Breach.008 - Security violation detected
C.Security.Intrusion.008 - Intrusion attempt detected7.4 Warning (W) - Examples
W.Api.Deprecated.010 - API method deprecated
W.Api.RateLimit.WARNING - Approaching rate limit
W.Cache.Miss.018 - Cache miss (degraded performance)
W.Cache.Expiring.018 - Cache entries expiring soon
W.Config.Default.USED - Using default configuration
W.Config.Missing.001 - Optional config missing
W.Parser.Ambiguous.003 - Ambiguous syntax (guessing)
W.Performance.Slow.017 - Operation slower than expected7.5 Help (H) - Examples
H.Usage.Tip.SUGGESTION - Helpful usage suggestion
H.Usage.Example.001 - Usage example
H.Perf.Optimization.001 - Performance optimization tip
H.Perf.Caching.001 - Consider enabling caching
H.Config.Recommended.001 - Recommended configuration
H.Config.BestPractice.001 - Configuration best practice
H.Security.BestPractice.001 - Security recommendation7.6 Success (S) - Examples
S.Auth.Login.SUCCESS - Login successful
S.Auth.Logout.SUCCESS - Logout successful
S.Upload.Complete.999 - File upload finished successfully
S.Download.Complete.999 - Download successful
S.Transaction.Commit.999 - Transaction committed
S.Validation.Pass.999 - Validation passed
S.Payment.Success.999 - Payment processed successfully7.7 Completed (K) - Examples
K.Build.Done.999 - Build completed
K.Build.Success.999 - Build successful
K.Migration.Finished.999 - Database migration finished
K.Migration.Rollback.999 - Rollback completed
K.Backup.Complete.999 - Backup completed
K.Backup.Verified.999 - Backup verified
K.BatchJob.Done.999 - Batch processing completed
K.Import.Finished.999 - Data import finished7.8 Info (I) - Examples
I.Server.Startup.001 - Server starting up
I.Server.Shutdown.001 - Server shutting down
I.Server.Ready.001 - Server ready to accept connections
I.Request.Received.001 - HTTP request received
I.Request.Processed.001 - Request processed
I.Cache.Stats.001 - Cache statistics
I.Cache.Hit.001 - Cache hit
I.Config.Loaded.001 - Configuration loaded
I.Config.Reloaded.001 - Configuration reloaded7.9 Trace (T) - Examples
T.Function.Entry.001 - Function entered (profiling)
T.Function.Exit.001 - Function exited
T.Timer.Start.001 - Timer started
T.Timer.Stop.001 - Timer stopped
T.Probe.Checkpoint.001 - Execution checkpoint
T.Probe.State.001 - State snapshot
T.Variable.Dump.001 - Variable state dump
T.Memory.Allocation.001 - Memory allocation trace8. Implementation Guide#
8.1 Defining Severity in Code
Rust:
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Severity {
Error = 8, // E
Blocked = 7, // B
Critical = 6, // C
Warning = 5, // W
Help = 4, // H
Success = 3, // S
Completed = 2, // K
Info = 1, // I
Trace = 0, // T
}
impl Severity {
pub fn code(&self) -> char {
match self {
Severity::Error => 'E',
Severity::Blocked => 'B',
Severity::Critical => 'C',
Severity::Warning => 'W',
Severity::Help => 'H',
Severity::Success => 'S',
Severity::Completed => 'K',
Severity::Info => 'I',
Severity::Trace => 'T',
}
}
pub fn priority(&self) -> u8 {
*self as u8
}
pub fn is_blocking(&self) -> bool {
matches!(self, Severity::Error | Severity::Blocked)
}
pub fn tone(&self) -> Tone {
match self {
Severity::Error | Severity::Blocked |
Severity::Critical | Severity::Warning => Tone::Negative,
Severity::Success | Severity::Completed => Tone::Positive,
Severity::Help | Severity::Info | Severity::Trace => Tone::Neutral,
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Tone {
Negative, // Problems/concerns
Positive, // Success/completion
Neutral, // Informational
}Python:
from enum import IntEnum
class Severity(IntEnum):
TRACE = 0 # T
INFO = 1 # I
COMPLETED = 2 # K
SUCCESS = 3 # S
HELP = 4 # H
WARNING = 5 # W
CRITICAL = 6 # C
BLOCKED = 7 # B
ERROR = 8 # E
def code(self) -> str:
codes = {
0: 'T', 1: 'I', 2: 'K', 3: 'S', 4: 'H',
5: 'W', 6: 'C', 7: 'B', 8: 'E'
}
return codes[self.value]
def is_blocking(self) -> bool:
return self in (Severity.ERROR, Severity.BLOCKED)
def tone(self) -> str:
if self in (Severity.ERROR, Severity.BLOCKED,
Severity.CRITICAL, Severity.WARNING):
return 'negative'
elif self in (Severity.SUCCESS, Severity.COMPLETED):
return 'positive'
else:
return 'neutral'TypeScript:
enum Severity {
Trace = 0, // T
Info = 1, // I
Completed = 2, // K
Success = 3, // S
Help = 4, // H
Warning = 5, // W
Critical = 6, // C
Blocked = 7, // B
Error = 8, // E
}
function severityCode(s: Severity): string {
const codes: Record<Severity, string> = {
[Severity.Trace]: 'T',
[Severity.Info]: 'I',
[Severity.Completed]: 'K',
[Severity.Success]: 'S',
[Severity.Help]: 'H',
[Severity.Warning]: 'W',
[Severity.Critical]: 'C',
[Severity.Blocked]: 'B',
[Severity.Error]: 'E',
};
return codes[s];
}
function severityTone(s: Severity): string {
if ([Severity.Error, Severity.Blocked,
Severity.Critical, Severity.Warning].includes(s)) {
return 'negative';
} else if ([Severity.Success, Severity.Completed].includes(s)) {
return 'positive';
} else {
return 'neutral';
}
}8.2 Parsing Severity from String
Validation:
fn parse_severity(c: char) -> Result<Severity, Error> {
match c {
'E' => Ok(Severity::Error),
'B' => Ok(Severity::Blocked),
'C' => Ok(Severity::Critical),
'W' => Ok(Severity::Warning),
'H' => Ok(Severity::Help),
'S' => Ok(Severity::Success),
'K' => Ok(Severity::Completed),
'I' => Ok(Severity::Info),
'T' => Ok(Severity::Trace),
_ => Err(Error::InvalidSeverity(c)),
}
}8.3 Filtering by Priority
fn filter_by_min_priority(codes: &[ErrorCode], min_priority: u8) -> Vec<ErrorCode> {
codes.iter()
.filter(|c| c.severity.priority() >= min_priority)
.cloned()
.collect()
}
// Usage:
let errors_and_warnings = filter_by_min_priority(&all_codes, 5);
let blocking_only = filter_by_min_priority(&all_codes, 7);8.4 Tone Classification Method (OPTIONAL)
Implementations MAY provide a tone() method for convenience when working with tone-based logic.
Purpose:
The tone() method simplifies filtering, routing, and analytics based on error tone without repeatedly matching on individual severity values.
Implementation:
pub fn tone(&self) -> Tone {
match self {
Severity::Error | Severity::Blocked |
Severity::Critical | Severity::Warning => Tone::Negative,
Severity::Success | Severity::Completed => Tone::Positive,
Severity::Help | Severity::Info | Severity::Trace => Tone::Neutral,
}
}Use Cases:
1. Filtering by tone:
// Get all problems
let problems = errors.iter()
.filter(|e| e.severity.tone() == Tone::Negative)
.collect::<Vec<_>>();
// Get all successes
let successes = errors.iter()
.filter(|e| e.severity.tone() == Tone::Positive)
.collect::<Vec<_>>();2. Analytics and dashboards:
fn system_health(errors: &[Error]) -> HealthScore {
let negative = errors.iter()
.filter(|e| e.severity.tone() == Tone::Negative)
.count();
let positive = errors.iter()
.filter(|e| e.severity.tone() == Tone::Positive)
.count();
HealthScore {
negative_count: negative,
positive_count: positive,
health_ratio: positive as f64 / (negative + positive) as f64,
}
}3. Alert routing:
match error.severity.tone() {
Tone::Negative => send_alert_to_oncall(&error),
Tone::Positive => send_notification(&error),
Tone::Neutral => log_only(&error),
}4. UI color coding:
fn severity_color(severity: &Severity) -> &'static str {
match severity.tone() {
Tone::Negative => "red",
Tone::Positive => "green",
Tone::Neutral => "blue",
}
}Note: This method is a convenience helper. Tone can always be determined by matching on the severity directly. Implementations that don't need tone-based logic may omit this method.
9. Examples#
9.1 Complete Error Codes by Severity
E.Auth.Token.001 - Error: Missing token
E.Database.Connection.021 - Error: Database not found
E.Parser.Syntax.003 - Error: Invalid syntax
B.Thread.Lock.024 - Blocked: Waiting for lock
B.Network.Connection.027 - Blocked: Network unavailable
B.Io.Timeout.017 - Blocked: I/O timeout
C.Data.Corruption.025 - Critical: Data corrupted
C.Memory.Exhausted.026 - Critical: Out of memory
C.Security.Breach.008 - Critical: Security violation
W.Api.Deprecated.010 - Warning: API deprecated
W.Cache.Miss.018 - Warning: Cache miss
W.Config.Missing.001 - Warning: Config missing
H.Usage.Tip.001 - Help: Usage suggestion
H.Perf.Optimization.001 - Help: Performance tip
H.Config.Recommended.001 - Help: Recommended config
S.Auth.Login.999 - Success: Login successful
S.Upload.Complete.999 - Success: Upload complete
S.Validation.Pass.999 - Success: Validation passed
K.Build.Done.999 - Completed: Build finished
K.Migration.Finished.999 - Completed: Migration done
K.Backup.Complete.999 - Completed: Backup complete
I.Server.Startup.001 - Info: Server starting
I.Request.Received.001 - Info: Request received
I.Config.Loaded.001 - Info: Configuration loaded
T.Function.Entry.001 - Trace: Function entered
T.Timer.Start.001 - Trace: Timer started
T.Checkpoint.001 - Trace: Checkpoint reachedAppendix A: Quick Reference#
Severity Table
| Code | Name | Priority | Blocking | Tone |
|---|---|---|---|---|
| E | Error | 8 | Yes | Negative |
| B | Blocked | 7 | Yes | Negative |
| C | Critical | 6 | No | Negative |
| W | Warning | 5 | No | Negative |
| H | Help | 4 | No | Neutral |
| S | Success | 3 | No | Positive |
| K | Completed | 2 | No | Positive |
| I | Info | 1 | No | Neutral |
| T | Trace | 0 | No | Neutral |
Priority Ordering
T(0) < I(1) < K(2) < S(3) < H(4) < W(5) < C(6) < B(7) < E(8)Regex
^[EWCBSHKIT]$Appendix B: References#
- STRUCTURE.md - Overview of WDP 5-part structure
- 2-COMPONENT.md - Part 2: Component field specification
- 3-PRIMARY.md - Part 3: Primary field specification
- 4-SEQUENCE.md - Part 4: Sequence field specification
- 5-COMPACT-IDS.md - Part 5: Compact ID (hash) specification