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.

Name an app's likely bottleneck on its Overview

Juan Denis3feba262cbdc
diff --git a/backend/app/api/app_attachments.py b/backend/app/api/app_attachments.py
index c2b6f1f7..b62741a8 100644
--- a/backend/app/api/app_attachments.py
+++ b/backend/app/api/app_attachments.py
@@ -119,3 +119,15 @@ def set_pooler(app_id):
raise ValidationError("'enabled' must be true or false")
result = pooler_service.set_enabled(app, data['enabled'])
return jsonify(result)
+
+
+# ==================== BOTTLENECK HINTS (plan 86 §A5) ====================
+
+@app_attachments_bp.route('/<int:app_id>/hints', methods=['GET'])
+@viewer_required
+def get_hints(app_id):
+ from app.services.bottleneck_hints_service import BottleneckHintsService
+ app = AppAttachmentService.live_app(app_id)
+ if app is None or not ResourceGrantService.can_access_app(get_current_user(), app):
+ raise NotFoundError('Application not found')
+ return jsonify({'hints': BottleneckHintsService.hints(app)})
diff --git a/backend/app/services/bottleneck_hints_service.py b/backend/app/services/bottleneck_hints_service.py
new file mode 100644
index 00000000..07a752f0
--- /dev/null
+++ b/backend/app/services/bottleneck_hints_service.py
@@ -0,0 +1,192 @@
+"""Name an app's likely bottleneck from what the panel measures (plan 86 §A5).
+
+A rule-based doctor, no AI: it reads the app's request metrics (§A2), its
+container's CPU, and, for a PostgreSQL / MySQL it reaches through
+``fromService``, that database's CPU and top queries (§A3). Each hint names
+the component that fits the signal, links to where it is set up, and states
+that component's failure mode. Nothing is ever added automatically.
+
+Each hint carries ``id`` + ``params`` (the numbers) for a translated UI, and
+English ``signal`` / ``hint`` / ``failure_mode`` text for API and CLI callers.
+
+Rules (all over the last 24 h):
+
+ slow + app busy + database idle → page cache (micro-cache) or a bigger box
+ slow + database busy + one query dominates → a cache, or an index
+ 5xx inside a deploy window → A/B slot deploys (plan 87)
+ micro-cache on, low hit ratio → the pages vary too much, or the TTL is short
+
+Not covered, deliberately: "large static share of bytes" and "slow POST
+endpoints" need per-path and per-method data that the rollups do not keep.
+"""
+from datetime import datetime, timedelta
+from typing import Callable, Dict, List, Optional
+
+SLOW_P95_MS = 1000
+BUSY_CPU_PERCENT = 80
+IDLE_CPU_PERCENT = 20
+DOMINANT_QUERY_SHARE = 0.5
+MIN_REQUESTS = 100
+LOW_HIT_RATIO = 0.3
+DEPLOY_WINDOW = timedelta(minutes=5)
+
+
+def _cpu_percent(container: str) -> Optional[float]:
+ from app.services.docker_service import DockerService
+ stats = DockerService.get_container_stats(container) or {}
+ raw = str(stats.get('CPUPerc') or '').rstrip('%')
+ try:
+ return float(raw)
+ except ValueError:
+ return None
+
+
+class BottleneckHintsService:
+ # Seams (tests replace these).
+ cpu_percent: Callable[[str], Optional[float]] = staticmethod(_cpu_percent)
+
+ @staticmethod
+ def _metrics(app) -> Dict:
+ from app.services.request_metrics_service import RequestMetricsService
+ return RequestMetricsService.series(app.id, '24h')
+
+ @staticmethod
+ def _databases(app) -> List:
+ """SQL engines this app reaches through fromService."""
+ from app.models import EnvironmentVariable
+ from app.services.env_reference_service import EnvReferenceResolver
+ from app.services.service_connection_service import _template_for
+ from app.services.template_service import TemplateService
+
+ found = {}
+ for ev in EnvironmentVariable.query.filter_by(application_id=app.id).all():
+ ref = ev.get_reference() if ev.value_from else None
+ if not ref or ref.get('kind') != 'service':
+ continue
+ sibling = EnvReferenceResolver.find_sibling_app(app, ref.get('service'))
+ if sibling is None:
+ continue
+ engine = TemplateService.engine_metadata(_template_for(sibling) or {}) or {}
+ if engine.get('protocol') in ('postgresql', 'mysql'):
+ found[sibling.id] = (sibling, engine)
+ return list(found.values())
+
+ @staticmethod
+ def _top_query_share(db_app, engine) -> Optional[float]:
+ from app.services.db_insights_service import DbInsightsService
+ from app.services.service_connection_service import ServiceConnectionService
+ props = (ServiceConnectionService.spec(db_app) or {}).get('properties', {})
+ target = {'engine': engine['protocol'], 'container': db_app.name,
+ 'user': props.get('username') or engine.get('admin_user'),
+ 'password': props.get('password'),
+ 'database': props.get('database') or None}
+ insights = DbInsightsService.insights(target)
+ queries = insights.get('top_queries') or []
+ total = sum(q.get('total_ms') or 0 for q in queries)
+ return (queries[0].get('total_ms') or 0) / total if total else None
+
+ @staticmethod
+ def _deploy_windows(app, since) -> List:
+ from app.models.deployment import Deployment
+ rows = Deployment.query.filter(Deployment.app_id == app.id,
+ Deployment.created_at >= since).all()
+ return [(d.deploy_started_at or d.created_at,
+ (d.deploy_completed_at or d.deploy_started_at or d.created_at) + DEPLOY_WINDOW)
+ for d in rows]
+
+ @classmethod
+ def _app_cpu(cls, app) -> Optional[float]:
+ """CPU of the app's container: the recorded id, then a template's
+ ``container_name: ${APP_NAME}``, then a build-pack deploy's name."""
+ for name in (getattr(app, 'container_id', None), app.name, f'serverkit-app-{app.id}'):
+ if name:
+ cpu = cls.cpu_percent(name)
+ if cpu is not None:
+ return cpu
+ return None
+
+ # ------------------------------------------------------------------
+
+ @classmethod
+ def hints(cls, app, now: Optional[datetime] = None) -> List[Dict]:
+ now = now or datetime.utcnow()
+ metrics = cls._metrics(app)
+ summary = metrics.get('summary') or {}
+ hints: List[Dict] = []
+ if (summary.get('requests') or 0) < MIN_REQUESTS:
+ return hints
+
+ p95 = summary.get('p95_ms')
+ if p95 is not None and p95 >= SLOW_P95_MS:
+ app_cpu = cls._app_cpu(app)
+ databases = cls._databases(app)
+ db_cpu = {db_app.name: cls.cpu_percent(db_app.name) for db_app, _ in databases}
+ busiest_db = max((v for v in db_cpu.values() if v is not None), default=None)
+
+ if app_cpu is not None and app_cpu >= BUSY_CPU_PERCENT and (
+ busiest_db is None or busiest_db <= IDLE_CPU_PERCENT):
+ hints.append({
+ 'id': 'app_bound',
+ 'params': {'p95_ms': round(p95), 'cpu': round(app_cpu)},
+ 'signal': f'p95 {p95:.0f} ms while the app uses {app_cpu:.0f}% CPU '
+ 'and its database is idle',
+ 'hint': 'The app itself is the bottleneck. Cache whole pages in front '
+ 'of it, or give it a bigger box. More copies of the app are '
+ 'not offered: one live copy per app.',
+ 'action': {'label': 'Micro-cache', 'target': 'settings/cache'},
+ 'failure_mode': 'A cached page can be stale for up to its lifetime.',
+ })
+ for db_app, engine in databases:
+ cpu = db_cpu.get(db_app.name)
+ if cpu is None or cpu < BUSY_CPU_PERCENT:
+ continue
+ share = cls._top_query_share(db_app, engine)
+ repeated = share is not None and share >= DOMINANT_QUERY_SHARE
+ hints.append({
+ 'id': 'database_bound',
+ 'params': {'p95_ms': round(p95), 'cpu': round(cpu), 'database': db_app.name,
+ 'share': round(share * 100) if repeated else None},
+ 'signal': (f'p95 {p95:.0f} ms while {db_app.name} uses {cpu:.0f}% CPU'
+ + (f'; one query takes {share:.0%} of its time' if repeated else '')),
+ 'hint': ('The database is the bottleneck. '
+ + ('The same query dominates: cache its result, or add an '
+ 'index for it (see the query in Insights).' if repeated else
+ 'Look at its top queries for a missing index, or cache '
+ 'what is read most.')),
+ 'action': {'label': 'Attach cache', 'target': 'overview#attachments'},
+ 'failure_mode': 'Cached data can be stale; invalidate on write.',
+ })
+
+ spikes = [p for p in metrics.get('points') or [] if (p.get('status_5xx') or 0) > 0]
+ if spikes:
+ windows = cls._deploy_windows(app, now - timedelta(hours=24))
+ during = [p for p in spikes if any(
+ start <= datetime.fromisoformat(p['t'].replace('Z', '+00:00')).replace(tzinfo=None) <= end
+ for start, end in windows)]
+ if during:
+ errors = sum(p['status_5xx'] for p in during)
+ hints.append({
+ 'id': 'deploy_errors',
+ 'params': {'errors': errors},
+ 'signal': f'{errors} server errors during deploys in the last 24 h',
+ 'hint': 'Visitors hit the gap while the old container stops and the '
+ 'new one starts. A/B slot deploys (plan 87) keep the old copy '
+ 'serving until the new one passes its health check.',
+ 'action': None,
+ 'failure_mode': 'Two copies run briefly during the switch; a migration '
+ 'must work with both.',
+ })
+
+ ratio = summary.get('cache_hit_ratio')
+ if getattr(app, 'micro_cache_enabled', False) and ratio is not None and ratio < LOW_HIT_RATIO:
+ hints.append({
+ 'id': 'low_hit_ratio',
+ 'params': {'ratio': round(ratio * 100)},
+ 'signal': f'micro-cache hit ratio {ratio:.0%}',
+ 'hint': 'Most cacheable requests miss. The pages may vary per visitor '
+ '(cookies, query strings bypass the cache), or the lifetime is '
+ 'too short for the traffic.',
+ 'action': {'label': 'Micro-cache', 'target': 'settings/cache'},
+ 'failure_mode': 'A longer lifetime serves older pages.',
+ })
+ return hints
diff --git a/backend/tests/test_bottleneck_hints.py b/backend/tests/test_bottleneck_hints.py
new file mode 100644
index 00000000..71a48b35
--- /dev/null
+++ b/backend/tests/test_bottleneck_hints.py
@@ -0,0 +1,144 @@
+"""Bottleneck hints from measured signals (plan 86 §A5). Every signal is
+scripted through the service's seams; nothing here touches Docker."""
+from datetime import datetime, timedelta
+from types import SimpleNamespace
+
+import pytest
+
+from app.services.bottleneck_hints_service import BottleneckHintsService as H
+
+NOW = datetime(2026, 7, 3, 12, 0)
+
+
+def _app(**kw):
+ return SimpleNamespace(**{'id': 1, 'name': 'shop', 'container_id': None,
+ 'micro_cache_enabled': False, **kw})
+
+
+def _metrics(p95=1500, requests=1000, ratio=None, points=()):
+ return {'summary': {'requests': requests, 'p95_ms': p95, 'cache_hit_ratio': ratio},
+ 'points': list(points)}
+
+
+def signals(monkeypatch):
+ state = {'metrics': _metrics(), 'cpu': {}, 'dbs': [], 'share': None, 'windows': []}
+ monkeypatch.setattr(H, '_metrics', staticmethod(lambda app: state['metrics']))
+ monkeypatch.setattr(H, 'cpu_percent', staticmethod(lambda name: state['cpu'].get(name)))
+ monkeypatch.setattr(H, '_databases', staticmethod(lambda app: state['dbs']))
+ monkeypatch.setattr(H, '_top_query_share', staticmethod(lambda db_app, engine: state['share']))
+ monkeypatch.setattr(H, '_deploy_windows', staticmethod(lambda app, since: state['windows']))
+ return state
+
+
+def _ids(app=None):
+ return [h['id'] for h in H.hints(app or _app(), now=NOW)]
+
+
+def test_a_busy_app_with_an_idle_database_points_at_the_page_cache(signals):
+ signals['cpu'] = {'shop': 95, 'pg': 5}
+ signals['dbs'] = [(SimpleNamespace(name='pg'), {'protocol': 'postgresql'})]
+ (hint,) = H.hints(_app(), now=NOW)
+ assert hint['id'] == 'app_bound'
+ assert hint['action']['target'] == 'settings/cache'
+ assert 'not offered' in hint['hint'], 'never suggests replicas'
+ assert hint['failure_mode']
+
+
+def test_a_busy_database_with_a_dominant_query_points_at_a_cache_or_index(signals):
+ signals['cpu'] = {'shop': 30, 'pg': 92}
+ signals['dbs'] = [(SimpleNamespace(name='pg'), {'protocol': 'postgresql'})]
+ signals['share'] = 0.7
+ (hint,) = H.hints(_app(), now=NOW)
+ assert hint['id'] == 'database_bound'
+ assert '70%' in hint['signal'] and 'index' in hint['hint']
+
+
+def test_fast_apps_get_no_performance_hint(signals):
+ signals['metrics'] = _metrics(p95=120)
+ signals['cpu'] = {'shop': 99}
+ assert _ids() == []
+
+
+def test_too_little_traffic_says_nothing(signals):
+ signals['metrics'] = _metrics(requests=20)
+ signals['cpu'] = {'shop': 99}
+ assert _ids() == []
+
+
+def test_errors_inside_a_deploy_window_point_at_slot_deploys(signals):
+ signals['metrics'] = _metrics(p95=50, points=[
+ {'t': '2026-07-03T11:00:00+00:00', 'status_5xx': 4},
+ {'t': '2026-07-03T09:00:00+00:00', 'status_5xx': 1},
+ ])
+ signals['windows'] = [(NOW - timedelta(hours=1, minutes=2), NOW - timedelta(minutes=55))]
+ (hint,) = H.hints(_app(), now=NOW)
+ assert hint['id'] == 'deploy_errors' and hint['signal'].startswith('4 server errors')
+
+
+def test_errors_outside_deploys_are_not_blamed_on_deploys(signals):
+ signals['metrics'] = _metrics(p95=50, points=[{'t': '2026-07-03T09:00:00+00:00', 'status_5xx': 3}])
+ signals['windows'] = [(NOW - timedelta(minutes=10), NOW - timedelta(minutes=5))]
+ assert _ids() == []
+
+
+def test_a_low_hit_ratio_only_matters_with_the_micro_cache_on(signals):
+ signals['metrics'] = _metrics(p95=50, ratio=0.1)
+ assert _ids() == []
+ assert _ids(_app(micro_cache_enabled=True)) == ['low_hit_ratio']
+
+
+def test_the_app_cpu_falls_back_through_its_container_names(signals):
+ signals['cpu'] = {'serverkit-app-1': 90}
+ assert _ids() == ['app_bound']
+
+
+def test_api(client, auth_headers, monkeypatch):
+ from tests.factories import make_application
+ from app import db
+ site = make_application(db, name='hinted')
+ monkeypatch.setattr(H, 'hints', classmethod(lambda cls, app, now=None: [{'id': 'x'}]))
+ resp = client.get(f'/api/v1/apps/{site.id}/hints', headers=auth_headers)
+ assert resp.status_code == 200 and resp.get_json() == {'hints': [{'id': 'x'}]}
+
+
+def test_databases_are_the_sql_engines_the_app_references(app, tmp_path, monkeypatch):
+ import json
+ from app import db
+ from app.models.deployment import Deployment
+ from app.services.env_service import EnvService
+ from app.services.template_service import TemplateService
+ from tests.factories import make_application
+ records = {}
+ monkeypatch.setattr(TemplateService, 'get_config', classmethod(
+ lambda cls: {'repos': [], 'installed': records}))
+ rows = {}
+ for name, template_id in (('pg', 'postgresql'), ('cache', 'redis'), ('web', None)):
+ root = tmp_path / name
+ root.mkdir()
+ if template_id:
+ (root / '.serverkit-template.json').write_text(json.dumps(
+ {'template_id': template_id, 'variables': {'DB_PASSWORD': 'x'}}))
+ rows[name] = make_application(db, name=name, root_path=str(root))
+ if template_id:
+ records[str(rows[name].id)] = {'template_id': template_id}
+ for key, svc in (('DATABASE_URL', 'pg'), ('REDIS_URL', 'cache')):
+ EnvService.set_env_reference(rows['web'].id, key,
+ {'kind': 'service', 'service': svc, 'property': 'url'})
+
+ found = H._databases(rows['web'])
+ assert [(a.name, e['protocol']) for a, e in found] == [('pg', 'postgresql')]
+
+ started = datetime.utcnow() - timedelta(hours=1)
+ db.session.add(Deployment(app_id=rows['web'].id, version=1, status='success',
+ deploy_started_at=started,
+ deploy_completed_at=started + timedelta(minutes=2)))
+ db.session.commit()
+ (window,) = H._deploy_windows(rows['web'], datetime.utcnow() - timedelta(hours=24))
+ assert window == (started, started + timedelta(minutes=2) + timedelta(minutes=5))
+
+
+def test_every_hint_carries_params_for_a_translated_ui(signals):
+ signals['cpu'] = {'shop': 95}
+ (hint,) = H.hints(_app(), now=NOW)
+ assert hint['params'] == {'p95_ms': 1500, 'cpu': 95}
diff --git a/docs/API_SURFACE.md b/docs/API_SURFACE.md
index a95b0815..27c52fe9 100644
--- a/docs/API_SURFACE.md
+++ b/docs/API_SURFACE.md
@@ -176,6 +176,7 @@ Regenerate (backend/):
- `GET /apps/{app_id}/env/history`
- `GET /apps/{app_id}/env/{key}`
- `GET /apps/{app_id}/grants`
+- `GET /apps/{app_id}/hints`
- `GET /apps/{app_id}/linked`
- `GET /apps/{app_id}/logs`
- `GET /apps/{app_id}/pooler`
diff --git a/frontend/src/components/service-detail/HintsCard.jsx b/frontend/src/components/service-detail/HintsCard.jsx
new file mode 100644
index 00000000..ff6375fb
--- /dev/null
+++ b/frontend/src/components/service-detail/HintsCard.jsx
@@ -0,0 +1,95 @@
+import { useEffect, useState } from 'react';
+import { Link } from 'react-router-dom';
+import { Lightbulb } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+import api from '../../services/api';
+
+// "Where is it slow?" (plan 86 §A5): rule-based hints from the app's request
+// metrics, its container CPU and its database. Each names the component that
+// fits the signal and that component's failure mode; nothing is ever added
+// for you. Renders nothing when there is no hint.
+export default function HintsCard({ app }) {
+ const { t } = useTranslation();
+ const [hints, setHints] = useState([]);
+
+ useEffect(() => {
+ let cancelled = false;
+ api.getAppHints(app.id)
+ .then((data) => { if (!cancelled) setHints(data.hints || []); })
+ .catch(() => {});
+ return () => { cancelled = true; };
+ }, [app.id]);
+
+ if (!hints.length) return null;
+
+ const text = (hint) => {
+ const p = hint.params || {};
+ switch (hint.id) {
+ case 'app_bound':
+ return {
+ signal: t('app.hints.appBoundSignal', 'p95 {{ms}} ms while the app uses {{cpu}}% CPU and its database is idle.', { ms: p.p95_ms, cpu: p.cpu }),
+ hint: t('app.hints.appBound', 'The app itself is the bottleneck. Cache whole pages in front of it, or give it a bigger box.'),
+ failure: t('app.hints.appBoundFailure', 'A cached page can be stale for up to its lifetime.'),
+ };
+ case 'database_bound':
+ return {
+ signal: p.share
+ ? t('app.hints.dbBoundSignalShare', 'p95 {{ms}} ms while {{db}} uses {{cpu}}% CPU; one query takes {{share}}% of its time.', { ms: p.p95_ms, db: p.database, cpu: p.cpu, share: p.share })
+ : t('app.hints.dbBoundSignal', 'p95 {{ms}} ms while {{db}} uses {{cpu}}% CPU.', { ms: p.p95_ms, db: p.database, cpu: p.cpu }),
+ hint: p.share
+ ? t('app.hints.dbBoundRepeated', 'The same query dominates: cache its result, or add an index for it (see the query in the database Insights tab).')
+ : t('app.hints.dbBound', 'The database is the bottleneck. Look at its top queries for a missing index, or cache what is read most.'),
+ failure: t('app.hints.dbBoundFailure', 'Cached data can be stale; invalidate on write.'),
+ };
+ case 'deploy_errors':
+ return {
+ signal: t('app.hints.deployErrorsSignal', '{{count}} server errors during deploys in the last 24 hours.', { count: p.errors }),
+ hint: t('app.hints.deployErrors', 'Visitors hit the gap while the old container stops and the new one starts. Slot deploys will keep the old copy serving until the new one passes its health check.'),
+ failure: t('app.hints.deployErrorsFailure', 'Two copies run briefly during the switch; a migration must work with both.'),
+ };
+ case 'low_hit_ratio':
+ return {
+ signal: t('app.hints.lowHitSignal', 'Micro-cache hit ratio {{ratio}}%.', { ratio: p.ratio }),
+ hint: t('app.hints.lowHit', 'Most cacheable requests miss. The pages may vary per visitor, or the cache lifetime is too short for the traffic.'),
+ failure: t('app.hints.lowHitFailure', 'A longer lifetime serves older pages.'),
+ };
+ default:
+ return { signal: hint.signal, hint: hint.hint, failure: hint.failure_mode };
+ }
+ };
+
+ const actionLink = (action) => {
+ if (!action) return null;
+ const label = action.target === 'settings/cache'
+ ? t('app.hints.openMicroCache', 'Open micro-cache settings')
+ : t('app.hints.attachCache', 'Attach a cache');
+ const to = action.target === 'settings/cache' ? `/services/${app.id}/settings/cache` : null;
+ return to
+ ? <Link to={to} className="hints__action">{label}</Link>
+ : <span className="hints__action hints__action--here">{label}</span>;
+ };
+
+ return (
+ <div className="overview-tab__card overview-tab__card--full hints">
+ <div className="overview-tab__card-header-row">
+ <h3 className="overview-tab__card-title">
+ <Lightbulb size={14} aria-hidden="true" /> {t('app.hints.title', 'Where it is slow')}
+ </h3>
+ <span className="hints__window">{t('app.hints.window', 'Last 24 hours')}</span>
+ </div>
+ <ul className="hints__list">
+ {hints.map((hint) => {
+ const copy = text(hint);
+ return (
+ <li key={hint.id} className="hints__item">
+ <p className="hints__signal">{copy.signal}</p>
+ <p className="hints__hint">{copy.hint}</p>
+ <p className="hints__failure">{copy.failure}</p>
+ {actionLink(hint.action)}
+ </li>
+ );
+ })}
+ </ul>
+ </div>
+ );
+}
diff --git a/frontend/src/components/service-detail/OverviewTab.jsx b/frontend/src/components/service-detail/OverviewTab.jsx
index 52f1ca99..7516f3ec 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 RequestMetricsCard from './RequestMetricsCard';
import AttachmentsCard from './AttachmentsCard';
import PoolerCard from './PoolerCard';
+import HintsCard from './HintsCard';
import { KpiBand, MetricCard, Pill, Gauge, EnvTag, statusKind } from '@/components/ds';
import { usePolling } from '@/hooks/usePolling';
import { useTranslation } from 'react-i18next';
@@ -332,6 +333,9 @@ const OverviewTab = ({ app, deployConfig }) => {
{/* Traffic (timed access log; hidden until requests exist) */}
<RequestMetricsCard appId={app.id} />
+ {/* Bottleneck hints from the traffic above (plan 86 §A5) */}
+ <HintsCard app={app} />
+
{/* Cache / storage / queue this app uses (plan 86 §C4) */}
<AttachmentsCard app={app} />
diff --git a/frontend/src/i18n/locales/en.json b/frontend/src/i18n/locales/en.json
index 655015f0..46507a2d 100644
--- a/frontend/src/i18n/locales/en.json
+++ b/frontend/src/i18n/locales/en.json
@@ -2686,6 +2686,26 @@
"gunicornConfiguration": "Gunicorn Configuration",
"loadingGunicornConfiguration": "Loading Gunicorn configuration…"
},
+ "hints": {
+ "appBound": "The app itself is the bottleneck. Cache whole pages in front of it, or give it a bigger box.",
+ "appBoundFailure": "A cached page can be stale for up to its lifetime.",
+ "appBoundSignal": "p95 {{ms}} ms while the app uses {{cpu}}% CPU and its database is idle.",
+ "attachCache": "Attach a cache",
+ "dbBound": "The database is the bottleneck. Look at its top queries for a missing index, or cache what is read most.",
+ "dbBoundFailure": "Cached data can be stale; invalidate on write.",
+ "dbBoundRepeated": "The same query dominates: cache its result, or add an index for it (see the query in the database Insights tab).",
+ "dbBoundSignal": "p95 {{ms}} ms while {{db}} uses {{cpu}}% CPU.",
+ "dbBoundSignalShare": "p95 {{ms}} ms while {{db}} uses {{cpu}}% CPU; one query takes {{share}}% of its time.",
+ "deployErrors": "Visitors hit the gap while the old container stops and the new one starts. Slot deploys will keep the old copy serving until the new one passes its health check.",
+ "deployErrorsFailure": "Two copies run briefly during the switch; a migration must work with both.",
+ "deployErrorsSignal": "{{count}} server errors during deploys in the last 24 hours.",
+ "lowHit": "Most cacheable requests miss. The pages may vary per visitor, or the cache lifetime is too short for the traffic.",
+ "lowHitFailure": "A longer lifetime serves older pages.",
+ "lowHitSignal": "Micro-cache hit ratio {{ratio}}%.",
+ "openMicroCache": "Open micro-cache settings",
+ "title": "Where it is slow",
+ "window": "Last 24 hours"
+ },
"htaccessConverter": {
"conversionFailed": "Conversion failed",
"convertHtaccess": "Convert .htaccess",
diff --git a/frontend/src/i18n/locales/es.json b/frontend/src/i18n/locales/es.json
index c89a1369..350eeab0 100644
--- a/frontend/src/i18n/locales/es.json
+++ b/frontend/src/i18n/locales/es.json
@@ -6769,6 +6769,26 @@
"savedNotApplied": "Guardado, pero no se pudo iniciar el pooler. Revisa los contenedores.",
"title": "Agrupación de conexiones",
"tradeoff": "La agrupación por transacción rompe funciones de sesión: sentencias preparadas en algunos drivers, LISTEN/NOTIFY, bloqueos consultivos y SET de sesión. Las apps mantienen la conexión directa salvo que cambien."
+ },
+ "hints": {
+ "appBound": "El cuello de botella es la propia app. Guarda páginas completas en caché delante de ella o dale una máquina más grande.",
+ "appBoundFailure": "Una página en caché puede estar desactualizada hasta que caduque.",
+ "appBoundSignal": "p95 de {{ms}} ms mientras la app usa {{cpu}}% de CPU y su base de datos está inactiva.",
+ "attachCache": "Conectar una caché",
+ "dbBound": "El cuello de botella es la base de datos. Revisa sus consultas principales por si falta un índice, o guarda en caché lo que más se lee.",
+ "dbBoundFailure": "Los datos en caché pueden quedar obsoletos; invalídalos al escribir.",
+ "dbBoundRepeated": "Domina la misma consulta: guarda su resultado en caché o añade un índice para ella (mira la consulta en la pestaña Estadísticas de la base de datos).",
+ "dbBoundSignal": "p95 de {{ms}} ms mientras {{db}} usa {{cpu}}% de CPU.",
+ "dbBoundSignalShare": "p95 de {{ms}} ms mientras {{db}} usa {{cpu}}% de CPU; una consulta ocupa el {{share}}% de su tiempo.",
+ "deployErrors": "Los visitantes caen en el hueco mientras el contenedor antiguo se detiene y arranca el nuevo. Los despliegues por ranuras mantendrán la copia antigua sirviendo hasta que la nueva pase su comprobación de salud.",
+ "deployErrorsFailure": "Durante el cambio corren dos copias un momento; una migración debe funcionar con ambas.",
+ "deployErrorsSignal": "{{count}} errores de servidor durante despliegues en las últimas 24 horas.",
+ "lowHit": "La mayoría de las solicitudes cacheables fallan. Las páginas pueden variar por visitante o la duración de la caché es demasiado corta para el tráfico.",
+ "lowHitFailure": "Una duración mayor sirve páginas más antiguas.",
+ "lowHitSignal": "Tasa de aciertos de la microcaché: {{ratio}}%.",
+ "openMicroCache": "Abrir ajustes de microcaché",
+ "title": "Dónde va lento",
+ "window": "Últimas 24 horas"
}
},
"auth": {
diff --git a/frontend/src/services/api/apps.js b/frontend/src/services/api/apps.js
index 63df99f2..5ffeb200 100644
--- a/frontend/src/services/api/apps.js
+++ b/frontend/src/services/api/apps.js
@@ -564,3 +564,8 @@ export async function getAppPooler(appId) {
export async function setAppPooler(appId, enabled) {
return this.request(`/apps/${appId}/pooler`, { method: 'PUT', body: { enabled } });
}
+
+// Rule-based bottleneck hints for an app (plan 86 §A5).
+export async function getAppHints(appId) {
+ return this.request(`/apps/${appId}/hints`);
+}
diff --git a/frontend/src/styles/pages/_bandwidth.scss b/frontend/src/styles/pages/_bandwidth.scss
index e6b96d7d..dd6321d9 100644
--- a/frontend/src/styles/pages/_bandwidth.scss
+++ b/frontend/src/styles/pages/_bandwidth.scss
@@ -257,3 +257,57 @@
&__tradeoff { color: var(--text-faint); }
}
+
+// Service detail Overview: bottleneck hints (plan 86 §A5).
+// Component: service-detail/HintsCard.
+.hints {
+ &__window {
+ font-size: 12px;
+ color: var(--text-dim);
+ }
+
+ &__list {
+ list-style: none;
+ margin: 0;
+ padding: 0;
+ display: flex;
+ flex-direction: column;
+ gap: 12px;
+ }
+
+ &__item {
+ display: flex;
+ flex-direction: column;
+ gap: 4px;
+ padding-top: 10px;
+ border-top: 1px solid var(--border-soft);
+
+ &:first-child { border-top: 0; padding-top: 0; }
+ }
+
+ &__signal {
+ margin: 0;
+ font-family: var(--mono);
+ font-size: 12.5px;
+ color: var(--text);
+ }
+
+ &__hint {
+ margin: 0;
+ font-size: 13px;
+ color: var(--text);
+ }
+
+ &__failure {
+ margin: 0;
+ font-size: 12px;
+ color: var(--text-dim);
+ }
+
+ &__action {
+ font-size: 12.5px;
+ color: var(--accent-bright);
+
+ &--here { color: var(--text-dim); }
+ }
+}