Skip to content

Revamp logging documentation with centralized guide #1155

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
khalidabuhakmeh merged 3 commits into from
Jul 17, 2026
Merged

Revamp logging documentation with centralized guide #1155

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9c21845
"Revamp logging documentation with new centralized 'Logging Fundament…
khalidabuhakmeh Jul 9, 2026
fee0fee
"Refine logging guide with grammar improvements, consistent phrasing,…
khalidabuhakmeh Jul 9, 2026
a8e634e
Apply suggestions from code review
khalidabuhakmeh Jul 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions astro/src/components/LogLevel.astro
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
---
// LogLevel.astro
// Renders a log level name with the appropriate color from the spectrum
// Uses mode-aware colors for optimal contrast in light and dark themes

interface Props {
level: 'Trace' | 'Debug' | 'Information' | 'Warning' | 'Error' | 'Critical';
}

const { level } = Astro.props;
---

<span class={`log-level log-level--${level.toLowerCase()}`}>{level}</span>

<style>
.log-level {
font-weight: 600;
}

/* Light mode (high contrast for white backgrounds) */
.log-level--trace { color: #57606a; }
.log-level--debug { color: #0550ae; }
.log-level--information { color: #0e6d6d; }
.log-level--warning { color: #9a6700; }
.log-level--error { color: #bc4c00; }
.log-level--critical { color: #cf222e; }

/* Dark mode (brighter for dark backgrounds) */
:global([data-theme='dark']) .log-level--trace { color: #8b949e; }
:global([data-theme='dark']) .log-level--debug { color: #58a6ff; }
:global([data-theme='dark']) .log-level--information { color: #3dbfbf; }
:global([data-theme='dark']) .log-level--warning { color: #d29922; }
:global([data-theme='dark']) .log-level--error { color: #f0883e; }
:global([data-theme='dark']) .log-level--critical { color: #f85149; }
</style>
307 changes: 307 additions & 0 deletions astro/src/components/LogLevelSpectrum.astro
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,307 @@

---
// LogLevelSpectrum.astro
// Visual anxiety-spectrum bar for log levels with quick-reference table
---

<div class="spectrum-wrapper">
<div class="spectrum-bar" aria-hidden="true">

<div class="segment trace">
<span class="level-name">Trace</span>
<span class="level-verb">Dev only</span>
<div class="tooltip">
<strong>What to do:</strong> Do not enable unless Duende Support requests it.
Expect sensitive data like tokens and PII.
</div>
</div>

<div class="segment debug">
<span class="level-name">Debug</span>
<span class="level-verb">Dev/Staging</span>
<div class="tooltip">
<strong>What to do:</strong> Enable temporarily during development or debugging.
Disable before deploying to production. May contain sensitive data.
</div>
</div>

<div class="segment information">
<span class="level-name">Information</span>
<span class="level-verb">Monitor</span>
<div class="tooltip">
<strong>What to do:</strong> No immediate action needed.
Use for auditing and request correlation in production.
</div>
</div>

<div class="segment warning">
<span class="level-name">Warning</span>
<span class="level-verb">Investigate</span>
<div class="tooltip">
<strong>What to do:</strong> Review when convenient.
May indicate misconfiguration or an edge case affecting some users.
</div>
</div>

<div class="segment error">
<span class="level-name">Error</span>
<span class="level-verb">Act soon</span>
<div class="tooltip">
<strong>What to do:</strong> Investigate promptly. Something failed.
Determine if users are affected and check for recurring patterns.
</div>
</div>

<div class="segment critical">
<span class="level-name">Critical</span>
<span class="level-verb">Act now!</span>
<div class="tooltip">
<strong>What to do:</strong> Act immediately. The system may be unable to
issue tokens. Escalate to your team or contact Duende Support.
</div>
</div>

</div>
<div class="spectrum-legend" aria-hidden="true">
<span>← Calm</span>
<span>Urgent →</span>
</div>

<!-- Quick reference table (always visible, accessible) -->
<table class="quick-ref-table">
<thead>
<tr>
<th>Level</th>
<th>Urgency</th>
<th class="action-col">Action</th>
</tr>
</thead>
<tbody>
<tr>
<td class="ref-level trace-text">Trace</td>
<td class="ref-urgency">Dev only</td>
<td>Support-requested diagnostics only. Contains sensitive data.</td>
</tr>
<tr>
<td class="ref-level debug-text">Debug</td>
<td class="ref-urgency">Dev/Staging</td>
<td>Enable in dev/staging. Disable before production. May contain sensitive data.</td>
</tr>
<tr>
<td class="ref-level info-text">Information</td>
<td class="ref-urgency">Monitor</td>
<td>Normal operations. Good default for production.</td>
</tr>
<tr>
<td class="ref-level warning-text">Warning</td>
<td class="ref-urgency">Investigate</td>
<td>Review when convenient. May indicate misconfiguration.</td>
</tr>
<tr>
<td class="ref-level error-text">Error</td>
<td class="ref-urgency">Act soon</td>
<td>Investigate promptly. Something failed.</td>
</tr>
<tr>
<td class="ref-level critical-text">Critical</td>
<td class="ref-urgency">Act now!</td>
<td>Act immediately. System may be down.</td>
</tr>
</tbody>
</table>
</div>

<style>
.spectrum-wrapper {
margin: 1.5rem 0 2rem;
user-select: none;
}

.spectrum-bar {
display: flex;
align-items: flex-end;
width: 100%;
gap: 3px;
}

.segment {
position: relative;
flex: 1;
display: flex;
flex-direction: column;
align-items: center;
padding: 0.85rem 0.35rem 0.7rem;
border-radius: 0.375rem;
cursor: default;
transition: transform 0.15s ease, filter 0.15s ease;
overflow: visible;
}

.segment:hover {
transform: translateY(-4px);
z-index: 10;
filter: brightness(1.12);
}

.level-name {
font-size: 0.85rem;
font-weight: 700;
text-transform: uppercase;
letter-spacing: 0.04em;
color: #fff;
white-space: nowrap;
}

.level-verb {
font-size: 0.75rem;
color: rgba(255, 255, 255, 0.9);
margin-top: 0.3rem;
white-space: nowrap;
}

/* Color spectrum: gray → blue-gray → teal/green → amber → orange → red */
.trace { background-color: #6b7280; }
.debug { background-color: #4a6fa5; }
.information { background-color: #0e7490; }
.warning { background-color: #d97706; }
.error { background-color: #ea580c; }
.critical { background-color: #dc2626; }

/* Tooltip */
.tooltip {
visibility: hidden;
opacity: 0;
position: absolute;
bottom: calc(100% + 10px);
left: 50%;
transform: translateX(-50%);
width: 220px;
background: #1e293b;
color: #f1f5f9;
padding: 0.6rem 0.75rem;
border-radius: 0.375rem;
font-size: 0.8rem;
line-height: 1.45;
pointer-events: none;
transition: opacity 0.15s ease;
box-shadow: 0 4px 14px rgba(0, 0, 0, 0.3);
z-index: 100;
white-space: normal;
text-align: left;
}

/* Caret */
.tooltip::after {
content: '';
position: absolute;
top: 100%;
left: 50%;
transform: translateX(-50%);
border: 6px solid transparent;
border-top-color: #1e293b;
}

.segment:hover .tooltip {
visibility: visible;
opacity: 1;
}

/* First segment: keep tooltip from clipping left edge */
.segment:first-child .tooltip {
left: 0;
transform: none;
}
.segment:first-child .tooltip::after {
left: 1.5rem;
transform: none;
}

/* Last segment: keep tooltip from clipping right edge */
.segment:last-child .tooltip {
left: auto;
right: 0;
transform: none;
}
.segment:last-child .tooltip::after {
left: auto;
right: 1.5rem;
transform: none;
}

/* Legend */
.spectrum-legend {
display: flex;
justify-content: space-between;
margin-top: 0.6rem;
font-size: 0.9rem;
font-weight: 600;
color: var(--sl-color-text, #ccc);
letter-spacing: 0.02em;
}

/* Quick reference table */
.quick-ref-table {
width: 100%;
margin-top: 1.25rem;
border-collapse: collapse;
font-size: 0.9rem;
table-layout: auto;
}

.quick-ref-table th,
.quick-ref-table td {
padding: 0.6rem 0.75rem;
text-align: left;
border-bottom: 1px solid var(--sl-color-gray-5, rgba(100, 100, 100, 0.2));
}

.quick-ref-table th {
font-weight: 600;
color: var(--sl-color-text-accent, #888);
font-size: 0.8rem;
text-transform: uppercase;
letter-spacing: 0.03em;
white-space: nowrap;
}

.quick-ref-table .action-col {
width: 100%;
}

.quick-ref-table tbody tr:last-child td {
border-bottom: none;
}

.ref-level {
font-weight: 600;
white-space: nowrap;
}

.ref-urgency {
white-space: nowrap;
color: var(--sl-color-text, #ccc);
}

/* Level colors for text */
.trace-text { color: #9ca3af; }
.debug-text { color: #6b8fc7; }
.info-text { color: #22d3ee; }
.warning-text { color: #fbbf24; }
.error-text { color: #fb923c; }
.critical-text { color: #f87171; }

/* Responsive: smaller text on mobile */
@media (max-width: 640px) {
.level-name {
font-size: 0.7rem;
}

.level-verb {
font-size: 0.65rem;
}

.quick-ref-table {
font-size: 0.8rem;
}
}
</style>
30 changes: 0 additions & 30 deletions astro/src/content/docs/accesstokenmanagement/advanced/logging.md
View file
Open in desktop

This file was deleted.

Loading
Loading