Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

fix(observability): resolve container runtime logs and metrics

jrbertt81a56012c34a
diff --git a/backend/app/api/apps.py b/backend/app/api/apps.py
index e2fe5b85..ab9f4b9d 100644
--- a/backend/app/api/apps.py
+++ b/backend/app/api/apps.py
@@ -2151,7 +2151,19 @@ def get_app_logs(app_id):
lines = request.args.get('lines', 100, type=int)
log_type = request.args.get('type', 'all')
- # For Docker apps, get docker compose logs
+ # A recorded container is the authoritative runtime for single-container
+ # deployments. Repositories may still contain an unrelated compose file,
+ # so file presence alone must not redirect their logs through compose.
+ if app.app_type == 'docker' and app.container_id:
+ if DockerService.get_container(app.container_id):
+ result = DockerService.get_container_logs(
+ app.container_id, tail=lines, timestamps=False
+ )
+ if result.get('success'):
+ return jsonify(result), 200
+
+ # Preserve the legacy Docker Compose path when there is no live recorded
+ # container (including old records that predate container_id tracking).
if app.app_type == 'docker' and app.root_path:
if app.server_id:
result = RemoteDockerService.compose_logs(
diff --git a/backend/tests/test_app_observability_runtime.py b/backend/tests/test_app_observability_runtime.py
new file mode 100644
index 00000000..ae29f85e
--- /dev/null
+++ b/backend/tests/test_app_observability_runtime.py
@@ -0,0 +1,91 @@
+"""Runtime-aware application logs keep single-container and compose support."""
+from unittest.mock import patch
+
+import pytest
+
+from factories import headers_for, make_application, make_user
+
+
+def owner(app, db_session):
+ return make_user(db_session, role='admin', username='observability-owner')
+
+
+def test_logs_prefer_a_live_recorded_container(client, db_session, owner, tmp_path):
+ """A repository compose file does not override the deployed runtime."""
+ (tmp_path / 'docker-compose.yaml').write_text(
+ 'services:\n db:\n image: postgres\n', encoding='utf-8')
+ application = make_application(
+ db_session,
+ name='standalone-api',
+ root_path=str(tmp_path),
+ compose_file=None,
+ container_id='runtime-container-id',
+ user_id=owner.id,
+ )
+
+ with patch('app.api.apps.DockerService.get_container',
+ return_value={'Id': 'runtime-container-id'}), \
+ patch('app.api.apps.DockerService.get_container_logs',
+ return_value={'success': True, 'logs': 'ready'}) as direct, \
+ patch('app.api.apps.LogService.get_docker_app_logs') as compose:
+ response = client.get(
+ f'/api/v1/apps/{application.id}/logs?lines=250',
+ headers=headers_for(owner),
+ )
+
+ assert response.status_code == 200
+ assert response.get_json()['logs'] == 'ready'
+ direct.assert_called_once_with(
+ 'runtime-container-id', tail=250, timestamps=False)
+ compose.assert_not_called()
+
+
+def test_logs_fall_back_to_compose_for_legacy_records(
+ client, db_session, owner, tmp_path):
+ application = make_application(
+ db_session,
+ name='legacy-compose',
+ root_path=str(tmp_path),
+ compose_file='compose.yaml',
+ container_id=None,
+ user_id=owner.id,
+ )
+
+ with patch('app.api.apps.LogService.get_docker_app_logs',
+ return_value={'success': True, 'logs': 'compose-ready'}) as compose:
+ response = client.get(
+ f'/api/v1/apps/{application.id}/logs?lines=75',
+ headers=headers_for(owner),
+ )
+
+ assert response.status_code == 200
+ assert response.get_json()['logs'] == 'compose-ready'
+ compose.assert_called_once_with(
+ 'legacy-compose', str(tmp_path), 75, compose_file='compose.yaml')
+
+
+def test_a_stale_recorded_container_keeps_the_compose_fallback(
+ client, db_session, owner, tmp_path):
+ application = make_application(
+ db_session,
+ name='recreated-compose',
+ root_path=str(tmp_path),
+ compose_file='compose.yaml',
+ container_id='removed-container-id',
+ user_id=owner.id,
+ )
+
+ with patch('app.api.apps.DockerService.get_container', return_value=None), \
+ patch('app.api.apps.DockerService.get_container_logs') as direct, \
+ patch('app.api.apps.LogService.get_docker_app_logs',
+ return_value={'success': True, 'logs': 'fallback-ready'}) as compose:
+ response = client.get(
+ f'/api/v1/apps/{application.id}/logs',
+ headers=headers_for(owner),
+ )
+
+ assert response.status_code == 200
+ assert response.get_json()['logs'] == 'fallback-ready'
+ direct.assert_not_called()
+ compose.assert_called_once()
diff --git a/frontend/src/components/service-detail/LogsTab.jsx b/frontend/src/components/service-detail/LogsTab.jsx
index 632a07c4..981f75f3 100644
--- a/frontend/src/components/service-detail/LogsTab.jsx
+++ b/frontend/src/components/service-detail/LogsTab.jsx
@@ -12,6 +12,7 @@ import { copyToClipboard } from '@/utils/clipboard';
import { downloadBlob } from '@/utils/downloadBlob';
import { usePolling } from '@/hooks/usePolling';
import { useTranslation } from 'react-i18next';
+import { parseStructuredLogLine } from '@/utils/structuredLog';
// Log tail refresh cadence while auto-refresh is on.
const LOG_REFRESH_MS = 5000;
@@ -113,11 +114,12 @@ const LogsTab = ({ app }) => {
const filteredLines = useMemo(() => {
if (!rawLogs) return [];
- let lines = rawLogs.split('\n');
+ let lines = rawLogs.split('\n').map(parseStructuredLogLine);
if (levelFilter !== 'all') {
- lines = lines.filter(line => {
- const lower = line.toLowerCase();
+ lines = lines.filter(entry => {
+ if (entry.level) return entry.level === levelFilter;
+ const lower = entry.raw.toLowerCase();
if (levelFilter === 'error') return lower.includes('error') || lower.includes('critical') || lower.includes('fatal');
if (levelFilter === 'warn') return lower.includes('warn');
if (levelFilter === 'info') return lower.includes('info');
@@ -128,14 +130,15 @@ const LogsTab = ({ app }) => {
if (searchTerm) {
const term = searchTerm.toLowerCase();
- lines = lines.filter(line => line.toLowerCase().includes(term));
+ lines = lines.filter(entry => entry.searchable.toLowerCase().includes(term));
}
return lines;
}, [rawLogs, searchTerm, levelFilter]);
- function getLineClass(line) {
- const lower = line.toLowerCase();
+ function getLineClass(entry) {
+ if (entry.level) return `logs-viewer__line--${entry.level}`;
+ const lower = entry.raw.toLowerCase();
if (lower.includes('error') || lower.includes('critical') || lower.includes('fatal')) return 'logs-viewer__line--error';
if (lower.includes('warn')) return 'logs-viewer__line--warn';
if (lower.includes('debug') || lower.includes('trace')) return 'logs-viewer__line--debug';
@@ -279,12 +282,28 @@ const LogsTab = ({ app }) => {
: 'No logs available.'}
</div>
) : (
- filteredLines.map((line, i) => (
- <div key={i} className={`logs-viewer__line ${getLineClass(line)}`}>
+ filteredLines.map((entry, i) => (
+ <div
+ key={`${i}-${entry.raw}`}
+ className={`logs-viewer__line ${entry.structured ? 'logs-viewer__line--structured' : ''} ${getLineClass(entry)}`}
+ >
<span className="logs-viewer__line-num">{i + 1}</span>
- <span className="logs-viewer__line-text">
- {searchTerm ? highlightSearch(line, searchTerm) : line}
- </span>
+ <div className="logs-viewer__line-text">
+ {entry.structured ? (
+ <>
+ {entry.timestamp && (
+ <span className="logs-viewer__timestamp">{entry.timestamp}</span>
+ )}
+ <pre className="logs-viewer__json">
+ {searchTerm
+ ? highlightSearch(entry.formatted, searchTerm)
+ : entry.formatted}
+ </pre>
+ </>
+ ) : (
+ searchTerm ? highlightSearch(entry.raw, searchTerm) : entry.raw
+ )}
+ </div>
</div>
))
)}
diff --git a/frontend/src/components/service-detail/MetricsTab.jsx b/frontend/src/components/service-detail/MetricsTab.jsx
index 1630c3bf..27907df7 100644
--- a/frontend/src/components/service-detail/MetricsTab.jsx
+++ b/frontend/src/components/service-detail/MetricsTab.jsx
@@ -4,6 +4,7 @@ import { Gauge } from '@/components/ds';
import EmptyState from '../EmptyState';
import { usePolling } from '@/hooks/usePolling';
import { useTranslation } from 'react-i18next';
+import { normalizeContainerStats, resolveAppContainerId } from '@/utils/containerMetrics';
// Live metrics cadence.
const METRICS_REFRESH_MS = 10000;
@@ -26,14 +27,11 @@ const MetricsTab = ({ app }) => {
try {
if (isDocker) {
const data = await api.getContainers(true);
- const appContainers = (data.containers || []).filter(c =>
- c.Names?.some(n => n.includes(app.name)) ||
- c.Labels?.['com.docker.compose.project'] === app.name
- );
-
- if (appContainers.length > 0) {
- const containerStats = await api.getContainerStats(appContainers[0].Id);
- setStats(containerStats);
+ const runtimeId = resolveAppContainerId(app, data.containers || []);
+ if (runtimeId) {
+ setStats(normalizeContainerStats(
+ await api.getContainerStats(runtimeId)
+ ));
}
} else if (isPython) {
const data = await api.getPythonAppStatus(app.id);
@@ -51,12 +49,12 @@ const MetricsTab = ({ app }) => {
}
if (isDocker && stats) {
- const cpuPercent = parseFloat(stats.cpu_percent || stats.CPUPerc || 0);
- const memPercent = parseFloat(stats.memory_percent || stats.MemPerc || 0);
- const memUsage = stats.memory_usage || stats.MemUsage || 'N/A';
- const netIO = stats.net_io || stats.NetIO || 'N/A';
- const blockIO = stats.block_io || stats.BlockIO || 'N/A';
- const pids = stats.pids || stats.PIDs || 'N/A';
+ const cpuPercent = stats.cpuPercent;
+ const memPercent = stats.memoryPercent;
+ const memUsage = stats.memoryUsage;
+ const netIO = stats.networkIO;
+ const blockIO = stats.blockIO;
+ const pids = stats.pids;
return (
<div className="metrics-tab">
diff --git a/frontend/src/components/service-detail/OverviewTab.jsx b/frontend/src/components/service-detail/OverviewTab.jsx
index a90e6b32..dcb142f6 100644
--- a/frontend/src/components/service-detail/OverviewTab.jsx
+++ b/frontend/src/components/service-detail/OverviewTab.jsx
@@ -11,6 +11,7 @@ import ScheduledTasksCard from '../ScheduledTasksCard';
import { KpiBand, MetricCard, Pill, Gauge, EnvTag, statusKind } from '@/components/ds';
import { usePolling } from '@/hooks/usePolling';
import { useTranslation } from 'react-i18next';
+import { normalizeContainerStats, resolveAppContainerId } from '@/utils/containerMetrics';
// Live metrics cadence.
const METRICS_REFRESH_MS = 10000;
@@ -64,32 +65,17 @@ const OverviewTab = ({ app, deployConfig }) => {
try {
if (isDocker) {
const data = await api.getContainers(true);
- // The API normalises `docker ps` into lowercase keys and does
- // not expose Labels at all, so matching on `Names[]` and the
- // compose-project label found nothing — Resource Usage came up
- // empty for every Docker service. The project can still be
- // matched through the container name it produces
- // (project-service-N).
- const needle = (app.name || '').toLowerCase();
- const appContainers = (data.containers || []).filter((c) => {
- const raw = c.name ?? c.Names ?? '';
- const text = Array.isArray(raw) ? raw.join(',') : String(raw);
- return needle && text.toLowerCase().includes(needle);
- });
- if (appContainers.length > 0) {
- const statsRes = await api.getContainerStats(
- appContainers[0].id ?? appContainers[0].Id);
- // The route answers {stats: {...}} with docker's own
- // CLI keys (CPUPerc, MemUsage, ...). Reading the top
- // level found nothing, so CPU and memory always showed
- // 0.0% and the rest N/A on a perfectly healthy container.
- const containerStats = statsRes?.stats ?? statsRes ?? {};
+ const runtimeId = resolveAppContainerId(app, data.containers || []);
+ if (runtimeId) {
+ const containerStats = normalizeContainerStats(
+ await api.getContainerStats(runtimeId)
+ );
setMetrics({
- cpu: parseFloat(containerStats.cpu_percent || containerStats.CPUPerc || 0),
- memory: parseFloat(containerStats.memory_percent || containerStats.MemPerc || 0),
- memUsage: containerStats.memory_usage || containerStats.MemUsage || 'N/A',
- netIO: containerStats.net_io || containerStats.NetIO || 'N/A',
- pids: containerStats.pids || containerStats.PIDs || 'N/A',
+ cpu: containerStats.cpuPercent,
+ memory: containerStats.memoryPercent,
+ memUsage: containerStats.memoryUsage,
+ netIO: containerStats.networkIO,
+ pids: containerStats.pids,
});
}
} else if (isPython) {
diff --git a/frontend/src/styles/pages/_service-detail.scss b/frontend/src/styles/pages/_service-detail.scss
index b1f31770..606783e1 100644
--- a/frontend/src/styles/pages/_service-detail.scss
+++ b/frontend/src/styles/pages/_service-detail.scss
@@ -1428,6 +1428,12 @@ h3.svc-eyebrow {
&--debug {
.logs-viewer__line-text { color: var(--text-faint); }
}
+
+ &--structured {
+ align-items: flex-start;
+ padding-block: $space-2;
+ border-bottom: 1px solid var(--border-soft);
+ }
}
&__line-num {
@@ -1441,11 +1447,29 @@ h3.svc-eyebrow {
&__line-text {
flex: 1;
+ min-width: 0;
color: var(--text-code);
white-space: pre-wrap;
word-break: break-all;
}
+ &__timestamp {
+ display: block;
+ margin-bottom: $space-1;
+ color: var(--text-faint);
+ font-size: 11px;
+ }
+
+ &__json {
+ margin: 0;
+ color: inherit;
+ font: inherit;
+ line-height: 1.55;
+ white-space: pre-wrap;
+ overflow-wrap: anywhere;
+ word-break: normal;
+ }
+
&__highlight {
background: rgba(245, 185, 69, 0.35);
color: var(--text);
diff --git a/frontend/src/utils/__tests__/containerMetrics.test.mjs b/frontend/src/utils/__tests__/containerMetrics.test.mjs
new file mode 100644
index 00000000..353a3d90
--- /dev/null
+++ b/frontend/src/utils/__tests__/containerMetrics.test.mjs
@@ -0,0 +1,67 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { normalizeContainerStats, resolveAppContainerId } from '../containerMetrics.js';
+
+test('prefers the recorded container id over repository or naming heuristics', () => {
+ assert.equal(
+ resolveAppContainerId(
+ { id: 3, name: 'findu-api-staging', container_id: 'recorded-id' },
+ [{ id: 'legacy-id', name: 'findu-api-staging-web-1' }]
+ ),
+ 'recorded-id'
+ );
+});
+
+test('falls back to generated and legacy container names', () => {
+ assert.equal(
+ resolveAppContainerId(
+ { id: 3, name: 'findu-api-staging' },
+ [{ id: 'generated-id', name: 'serverkit-app-3' }]
+ ),
+ 'generated-id'
+ );
+ assert.equal(
+ resolveAppContainerId(
+ { id: 7, name: 'legacy-api' },
+ [{ ID: 'legacy-id', Names: ['/legacy-api-web-1'] }]
+ ),
+ 'legacy-id'
+ );
+});
+
+test('normalizes wrapped Docker CLI stats', () => {
+ assert.deepEqual(normalizeContainerStats({ stats: {
+ CPUPerc: '1.25%',
+ MemPerc: '2.50%',
+ MemUsage: '50MiB / 2GiB',
+ NetIO: '1MB / 2MB',
+ BlockIO: '3MB / 4MB',
+ PIDs: '12',
+ } }), {
+ cpuPercent: 1.25,
+ memoryPercent: 2.5,
+ memoryUsage: '50MiB / 2GiB',
+ networkIO: '1MB / 2MB',
+ blockIO: '3MB / 4MB',
+ pids: '12',
+ });
+});
+
+test('keeps compatibility with the historical normalized shape', () => {
+ assert.deepEqual(normalizeContainerStats({
+ cpu_percent: '0.5',
+ memory_percent: '1.5',
+ memory_usage: '10MiB',
+ net_io: '5kB',
+ block_io: '8kB',
+ pids: 4,
+ }), {
+ cpuPercent: 0.5,
+ memoryPercent: 1.5,
+ memoryUsage: '10MiB',
+ networkIO: '5kB',
+ blockIO: '8kB',
+ pids: 4,
+ });
+});
diff --git a/frontend/src/utils/__tests__/structuredLog.test.mjs b/frontend/src/utils/__tests__/structuredLog.test.mjs
new file mode 100644
index 00000000..f27a466f
--- /dev/null
+++ b/frontend/src/utils/__tests__/structuredLog.test.mjs
@@ -0,0 +1,38 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { parseStructuredLogLine } from '../structuredLog.js';
+
+test('formats a Pino JSON line as a readable object', () => {
+ const result = parseStructuredLogLine(
+ '{"level":30,"cpf":"000.000.000-00","cacheHit":true}'
+ );
+
+ assert.equal(result.structured, true);
+ assert.equal(result.level, 'info');
+ assert.equal(
+ result.formatted,
+ '{\n "level": 30,\n "cpf": "000.000.000-00",\n "cacheHit": true\n}'
+ );
+});
+
+test('separates a Docker timestamp from a structured payload', () => {
+ const result = parseStructuredLogLine(
+ '2026-09-05T10:48:00.000000000Z {"level":40,"msg":"Rejected"}'
+ );
+
+ assert.equal(result.structured, true);
+ assert.equal(result.timestamp, '2026-09-05T10:48:00.000000000Z');
+ assert.equal(result.level, 'warn');
+});
+
+test('leaves plain and malformed log lines unchanged', () => {
+ const plain = parseStructuredLogLine('Application started');
+ const malformed = parseStructuredLogLine('{not-json}');
+
+ assert.equal(plain.structured, false);
+ assert.equal(plain.raw, 'Application started');
+ assert.equal(malformed.structured, false);
+ assert.equal(malformed.raw, '{not-json}');
+});
+
diff --git a/frontend/src/utils/containerMetrics.js b/frontend/src/utils/containerMetrics.js
new file mode 100644
index 00000000..ac883156
--- /dev/null
+++ b/frontend/src/utils/containerMetrics.js
@@ -0,0 +1,50 @@
+function containerId(container) {
+ return container?.id ?? container?.Id ?? container?.ID ?? null;
+}
+
+function containerNames(container) {
+ const raw = container?.name ?? container?.Names ?? '';
+ return Array.isArray(raw) ? raw : String(raw).split(',').filter(Boolean);
+}
+
+/**
+ * Resolve an application's runtime without dropping support for legacy
+ * container-list payloads and compose labels.
+ */
+export function resolveAppContainerId(app, containers = []) {
+ if (app?.container_id) return app.container_id;
+
+ const appName = String(app?.name || '').toLowerCase();
+ const generatedName = app?.id ? `serverkit-app-${app.id}` : '';
+ const match = containers.find((container) => {
+ const names = containerNames(container).map((name) => name.toLowerCase());
+ const labels = container?.Labels ?? container?.labels ?? {};
+ const composeProject = typeof labels === 'object'
+ ? labels['com.docker.compose.project']
+ : '';
+
+ return (generatedName && names.some((name) => name === generatedName))
+ || (appName && names.some((name) => name.includes(appName)))
+ || (appName && String(composeProject || '').toLowerCase() === appName);
+ });
+
+ return containerId(match);
+}
+
+function percent(value) {
+ const parsed = Number.parseFloat(value ?? 0);
+ return Number.isFinite(parsed) ? parsed : 0;
+}
+
+/** Accept both the wrapped API response and the historical raw Docker shape. */
+export function normalizeContainerStats(response) {
+ const stats = response?.stats ?? response ?? {};
+ return {
+ cpuPercent: percent(stats.cpu_percent ?? stats.CPUPerc),
+ memoryPercent: percent(stats.memory_percent ?? stats.MemPerc),
+ memoryUsage: stats.memory_usage ?? stats.MemUsage ?? 'N/A',
+ networkIO: stats.net_io ?? stats.NetIO ?? 'N/A',
+ blockIO: stats.block_io ?? stats.BlockIO ?? 'N/A',
+ pids: stats.pids ?? stats.PIDs ?? 'N/A',
+ };
+}
diff --git a/frontend/src/utils/structuredLog.js b/frontend/src/utils/structuredLog.js
new file mode 100644
index 00000000..16118195
--- /dev/null
+++ b/frontend/src/utils/structuredLog.js
@@ -0,0 +1,62 @@
+const DOCKER_TIMESTAMP = /^(\d{4}-\d{2}-\d{2}T\S+)\s+(.*)$/;
+
+function normalizeLevel(value) {
+ if (typeof value === 'number') {
+ if (value >= 50) return 'error';
+ if (value >= 40) return 'warn';
+ if (value >= 30) return 'info';
+ return 'debug';
+ }
+
+ if (typeof value !== 'string') return null;
+ const level = value.toLowerCase();
+ if (level === 'warning') return 'warn';
+ if (level === 'fatal' || level === 'critical') return 'error';
+ if (['error', 'warn', 'info', 'debug', 'trace'].includes(level)) {
+ return level === 'trace' ? 'debug' : level;
+ }
+ return null;
+}
+
+export function parseStructuredLogLine(line) {
+ const timestampMatch = line.match(DOCKER_TIMESTAMP);
+ const timestamp = timestampMatch?.[1] || '';
+ const content = timestampMatch?.[2] || line;
+
+ if (!content.trimStart().startsWith('{')) {
+ return {
+ raw: line,
+ searchable: line,
+ structured: false,
+ timestamp,
+ level: null,
+ };
+ }
+
+ try {
+ const payload = JSON.parse(content);
+ if (!payload || Array.isArray(payload) || typeof payload !== 'object') {
+ throw new TypeError('Structured log payload must be an object');
+ }
+
+ const formatted = JSON.stringify(payload, null, 2);
+ return {
+ raw: line,
+ searchable: timestamp ? `${timestamp}\n${formatted}` : formatted,
+ structured: true,
+ timestamp,
+ payload,
+ formatted,
+ level: normalizeLevel(payload.level),
+ };
+ } catch {
+ return {
+ raw: line,
+ searchable: line,
+ structured: false,
+ timestamp,
+ level: null,
+ };
+ }
+}
+