mongo-x-ray-ftdc 2.0.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- mongo_x_ray_ftdc/__init__.py +11 -0
- mongo_x_ray_ftdc/ai.py +146 -0
- mongo_x_ray_ftdc/charts.py +500 -0
- mongo_x_ray_ftdc/framework.py +189 -0
- mongo_x_ray_ftdc/ftdc_items/__init__.py +11 -0
- mongo_x_ray_ftdc/ftdc_items/base_item.py +42 -0
- mongo_x_ray_ftdc/ftdc_items/baseline_analysis_item.py +790 -0
- mongo_x_ray_ftdc/ftdc_items/metadata_review_item.py +108 -0
- mongo_x_ray_ftdc/parsers/__init__.py +11 -0
- mongo_x_ray_ftdc/parsers/base_parser.py +21 -0
- mongo_x_ray_ftdc/parsers/baseline_analysis_parser.py +116 -0
- mongo_x_ray_ftdc/plugin.py +134 -0
- mongo_x_ray_ftdc/shared.py +263 -0
- mongo_x_ray_ftdc/templates/ftdc/full.html +1 -0
- mongo_x_ray_ftdc/templates/ftdc/full.raw.html +29 -0
- mongo_x_ray_ftdc/templates/ftdc/script.js +1 -0
- mongo_x_ray_ftdc/templates/ftdc/script.raw.js +13 -0
- mongo_x_ray_ftdc/templates/ftdc/style.css +1 -0
- mongo_x_ray_ftdc/templates/ftdc/style.raw.css +36 -0
- mongo_x_ray_ftdc/templates/minify.sh +51 -0
- mongo_x_ray_ftdc-2.0.0.dist-info/METADATA +135 -0
- mongo_x_ray_ftdc-2.0.0.dist-info/RECORD +25 -0
- mongo_x_ray_ftdc-2.0.0.dist-info/WHEEL +5 -0
- mongo_x_ray_ftdc-2.0.0.dist-info/entry_points.txt +2 -0
- mongo_x_ray_ftdc-2.0.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Copyright (c) 2026 MongoDB Inc.
|
|
3
|
+
|
|
4
|
+
DISCLAIMER: THESE CODE SAMPLES ARE PROVIDED FOR EDUCATIONAL AND ILLUSTRATIVE PURPOSES ONLY,
|
|
5
|
+
TO DEMONSTRATE THE FUNCTIONALITY OF SPECIFIC MONGODB FEATURES.
|
|
6
|
+
THEY ARE NOT PRODUCTION-READY AND MAY LACK THE SECURITY HARDENING, ERROR HANDLING, AND TESTING REQUIRED FOR A LIVE ENVIRONMENT.
|
|
7
|
+
YOU ARE RESPONSIBLE FOR TESTING, VALIDATING, AND SECURING THIS CODE WITHIN YOUR OWN ENVIRONMENT BEFORE IMPLEMENTATION.
|
|
8
|
+
THIS MATERIAL IS PROVIDED "AS IS" WITHOUT WARRANTY OR LIABILITY.
|
|
9
|
+
|
|
10
|
+
MongoDB FTDC analysis package.
|
|
11
|
+
"""
|
mongo_x_ray_ftdc/ai.py
ADDED
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Copyright (c) 2026 MongoDB Inc.
|
|
3
|
+
|
|
4
|
+
DISCLAIMER: THESE CODE SAMPLES ARE PROVIDED FOR EDUCATIONAL AND ILLUSTRATIVE PURPOSES ONLY,
|
|
5
|
+
TO DEMONSTRATE THE FUNCTIONALITY OF SPECIFIC MONGODB FEATURES.
|
|
6
|
+
THEY ARE NOT PRODUCTION-READY AND MAY LACK THE SECURITY HARDENING, ERROR HANDLING, AND TESTING REQUIRED FOR A LIVE ENVIRONMENT.
|
|
7
|
+
YOU ARE RESPONSIBLE FOR TESTING, VALIDATING, AND SECURING THIS CODE WITHIN YOUR OWN ENVIRONMENT BEFORE IMPLEMENTATION.
|
|
8
|
+
THIS MATERIAL IS PROVIDED "AS IS" WITHOUT WARRANTY OR LIABILITY.
|
|
9
|
+
|
|
10
|
+
AI analysis helpers for FTDC reports.
|
|
11
|
+
|
|
12
|
+
These functions build the FTDC metric prompts and send them through the
|
|
13
|
+
shared client in :mod:`mongo_x_ray.ai_client`.
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
from __future__ import annotations
|
|
17
|
+
|
|
18
|
+
import json
|
|
19
|
+
import logging
|
|
20
|
+
|
|
21
|
+
from mongo_x_ray.ai_client import complete
|
|
22
|
+
|
|
23
|
+
_logger = logging.getLogger(__name__)
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def _build_section_prompt(section_title: str, metrics_data: list[dict[str, object]]) -> str:
|
|
27
|
+
"""Build the prompt for a single FTDC section."""
|
|
28
|
+
parts = [
|
|
29
|
+
"You are analyzing MongoDB FTDC (Full-Time Diagnostic Data Capture) "
|
|
30
|
+
+ "metrics from a 24-hour monitoring period.",
|
|
31
|
+
"",
|
|
32
|
+
f"## {section_title}",
|
|
33
|
+
"",
|
|
34
|
+
"Each metric below has ~1440 data points, sampled every 60 seconds "
|
|
35
|
+
+ "from the raw 1-second FTDC data. Values are provided as a JSON array.",
|
|
36
|
+
"",
|
|
37
|
+
]
|
|
38
|
+
|
|
39
|
+
for entry in metrics_data:
|
|
40
|
+
metric = entry["metric"]
|
|
41
|
+
unit = entry.get("unit", "")
|
|
42
|
+
peak = entry.get("peak", "N/A")
|
|
43
|
+
avg = entry.get("average", "N/A")
|
|
44
|
+
values = entry.get("values", [])
|
|
45
|
+
|
|
46
|
+
parts.append(f"### {metric}")
|
|
47
|
+
parts.append(f"- Unit: {unit}")
|
|
48
|
+
parts.append(f"- Peak: {peak}")
|
|
49
|
+
parts.append(f"- Average: {avg}")
|
|
50
|
+
parts.append(f"- Values: {json.dumps(values)}")
|
|
51
|
+
parts.append("")
|
|
52
|
+
|
|
53
|
+
parts.extend(
|
|
54
|
+
[
|
|
55
|
+
"Provide a very brief summary (2-3 sentences) indicating whether "
|
|
56
|
+
+ "these metrics show any potential issues that need attention. "
|
|
57
|
+
+ "If everything looks normal, simply state that no obvious "
|
|
58
|
+
+ "problems were detected.",
|
|
59
|
+
]
|
|
60
|
+
)
|
|
61
|
+
|
|
62
|
+
return "\n".join(parts)
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def analyze_ftdc_section(
|
|
66
|
+
section_title: str,
|
|
67
|
+
metrics_data: list[dict[str, object]],
|
|
68
|
+
) -> str | None:
|
|
69
|
+
"""Send a section's FTDC metrics to the AI for analysis.
|
|
70
|
+
|
|
71
|
+
Args:
|
|
72
|
+
section_title: e.g. ``"1.1 Workload"``.
|
|
73
|
+
metrics_data: List of dicts with keys:
|
|
74
|
+
- ``metric``: metric display name
|
|
75
|
+
- ``unit``: unit string (e.g. ``"ops/s"``)
|
|
76
|
+
- ``peak``: peak value
|
|
77
|
+
- ``average``: average value
|
|
78
|
+
- ``values``: list of ~1440 downsampled float values
|
|
79
|
+
|
|
80
|
+
Returns:
|
|
81
|
+
AI analysis text, or ``None`` if the AI client is not configured.
|
|
82
|
+
"""
|
|
83
|
+
prompt = _build_section_prompt(section_title, metrics_data)
|
|
84
|
+
_logger.info(
|
|
85
|
+
"Sending AI analysis request for %s (%d metrics, %d chars)",
|
|
86
|
+
section_title,
|
|
87
|
+
len(metrics_data),
|
|
88
|
+
len(prompt),
|
|
89
|
+
)
|
|
90
|
+
return complete(prompt)
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
def analyze_ftdc_overview(metrics_data: list[dict[str, object]]) -> str | None:
|
|
94
|
+
"""Send all metrics from all sections to AI for cross-section correlation analysis.
|
|
95
|
+
|
|
96
|
+
Args:
|
|
97
|
+
metrics_data: Combined list of all metrics across all sections.
|
|
98
|
+
|
|
99
|
+
Returns:
|
|
100
|
+
AI overview text, or ``None`` if the AI client is not configured.
|
|
101
|
+
"""
|
|
102
|
+
prompt_parts = [
|
|
103
|
+
"You are analyzing MongoDB FTDC metrics from a 24-hour monitoring "
|
|
104
|
+
+ "period. Below are ALL metrics from every section (Workload, "
|
|
105
|
+
+ "Ops and Latencies, Performance) combined.",
|
|
106
|
+
"",
|
|
107
|
+
"## Cross-Section Overview",
|
|
108
|
+
"",
|
|
109
|
+
"For each metric, the downsampled values (~1440 points each) and summary statistics are provided.",
|
|
110
|
+
"",
|
|
111
|
+
]
|
|
112
|
+
|
|
113
|
+
for entry in metrics_data:
|
|
114
|
+
metric = entry["metric"]
|
|
115
|
+
unit = entry.get("unit", "")
|
|
116
|
+
peak = entry.get("peak", "N/A")
|
|
117
|
+
avg = entry.get("average", "N/A")
|
|
118
|
+
values = entry.get("values", [])
|
|
119
|
+
|
|
120
|
+
prompt_parts.append(f"### {metric}")
|
|
121
|
+
prompt_parts.append(f"- Unit: {unit}")
|
|
122
|
+
prompt_parts.append(f"- Peak: {peak}")
|
|
123
|
+
prompt_parts.append(f"- Average: {avg}")
|
|
124
|
+
prompt_parts.append(f"- Values: {json.dumps(values)}")
|
|
125
|
+
prompt_parts.append("")
|
|
126
|
+
|
|
127
|
+
prompt_parts.extend(
|
|
128
|
+
[
|
|
129
|
+
"Look across ALL the above metrics and provide a brief overview "
|
|
130
|
+
+ "(2-3 sentences) of any correlations or relationships between "
|
|
131
|
+
+ "metrics from different sections. For example:",
|
|
132
|
+
"- Does high workload correlate with increased latency?",
|
|
133
|
+
"- Does CPU or memory pressure coincide with cache changes?",
|
|
134
|
+
"- Are there any cascading effects visible across sections?",
|
|
135
|
+
"",
|
|
136
|
+
"If no notable cross-section patterns are found, simply state that.",
|
|
137
|
+
]
|
|
138
|
+
)
|
|
139
|
+
|
|
140
|
+
prompt = "\n".join(prompt_parts)
|
|
141
|
+
_logger.info(
|
|
142
|
+
"Sending AI overview request (%d metrics, %d chars)",
|
|
143
|
+
len(metrics_data),
|
|
144
|
+
len(prompt),
|
|
145
|
+
)
|
|
146
|
+
return complete(prompt)
|
|
@@ -0,0 +1,500 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Copyright (c) 2026 MongoDB Inc.
|
|
3
|
+
|
|
4
|
+
DISCLAIMER: THESE CODE SAMPLES ARE PROVIDED FOR EDUCATIONAL AND ILLUSTRATIVE PURPOSES ONLY,
|
|
5
|
+
TO DEMONSTRATE THE FUNCTIONALITY OF SPECIFIC MONGODB FEATURES.
|
|
6
|
+
THEY ARE NOT PRODUCTION-READY AND MAY LACK THE SECURITY HARDENING, ERROR HANDLING, AND TESTING REQUIRED FOR A LIVE ENVIRONMENT.
|
|
7
|
+
YOU ARE RESPONSIBLE FOR TESTING, VALIDATING, AND SECURING THIS CODE WITHIN YOUR OWN ENVIRONMENT BEFORE IMPLEMENTATION.
|
|
8
|
+
THIS MATERIAL IS PROVIDED "AS IS" WITHOUT WARRANTY OR LIABILITY.
|
|
9
|
+
|
|
10
|
+
Reusable chart rendering for FTDC analysis reports.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
import re
|
|
14
|
+
from datetime import datetime, timedelta
|
|
15
|
+
from html import escape
|
|
16
|
+
from math import isfinite
|
|
17
|
+
from pathlib import Path
|
|
18
|
+
from typing import Literal, Mapping, Optional, Sequence, Union
|
|
19
|
+
|
|
20
|
+
BAR_COLORS = frozenset({"blue", "gray", "green", "red", "yellow"})
|
|
21
|
+
DEFAULT_CHART_WIDTH = 500
|
|
22
|
+
DEFAULT_CHART_HEIGHT = 150
|
|
23
|
+
MEMBER_STATE_CHART_WIDTH = 500
|
|
24
|
+
MEMBER_STATE_CHART_HEIGHT = 66
|
|
25
|
+
|
|
26
|
+
_BAR_COLOR_HEX: dict[Optional[str], str] = {
|
|
27
|
+
None: "#0072b2",
|
|
28
|
+
"green": "#009e73",
|
|
29
|
+
"yellow": "#e69f00",
|
|
30
|
+
"red": "#cc3311",
|
|
31
|
+
"blue": "#0072b2",
|
|
32
|
+
"gray": "#667085",
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
_TEXT_COLOR = "#57606a"
|
|
36
|
+
_AXIS_COLOR = "#8c959f"
|
|
37
|
+
_GRID_COLOR = "#d0d7de"
|
|
38
|
+
_X_GRID_SPACING = 100
|
|
39
|
+
_Y_GRID_SPACING = 50
|
|
40
|
+
|
|
41
|
+
_LEFT, _RIGHT, _TOP, _BOTTOM = 52, 28, 8, 24
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def _parse_thresholds(
|
|
45
|
+
thresholds: Optional[tuple[float, float]],
|
|
46
|
+
) -> Optional[tuple[float, float]]:
|
|
47
|
+
if thresholds is None:
|
|
48
|
+
return None
|
|
49
|
+
if not isinstance(thresholds, (list, tuple)) or len(thresholds) != 2:
|
|
50
|
+
raise ValueError("chart thresholds must contain exactly two numbers")
|
|
51
|
+
if any(isinstance(threshold, bool) for threshold in thresholds):
|
|
52
|
+
raise ValueError("chart thresholds must contain exactly two numbers")
|
|
53
|
+
try:
|
|
54
|
+
lower, upper = (float(threshold) for threshold in thresholds)
|
|
55
|
+
except (TypeError, ValueError) as exc:
|
|
56
|
+
raise ValueError("chart thresholds must contain exactly two numbers") from exc
|
|
57
|
+
if not isfinite(lower) or not isfinite(upper) or lower >= upper:
|
|
58
|
+
raise ValueError("chart thresholds must be finite and ordered from lowest to highest")
|
|
59
|
+
return lower, upper
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def _parse_value_colors(
|
|
63
|
+
value_colors: Optional[Mapping[float, str]],
|
|
64
|
+
) -> Optional[dict[float, str]]:
|
|
65
|
+
if value_colors is None:
|
|
66
|
+
return None
|
|
67
|
+
if not isinstance(value_colors, Mapping):
|
|
68
|
+
raise ValueError("chart value colors must map finite numbers to supported colors")
|
|
69
|
+
|
|
70
|
+
parsed = {}
|
|
71
|
+
for value, color in value_colors.items():
|
|
72
|
+
if isinstance(value, bool):
|
|
73
|
+
raise ValueError("chart value colors must map finite numbers to supported colors")
|
|
74
|
+
try:
|
|
75
|
+
numeric_value = float(value)
|
|
76
|
+
except (TypeError, ValueError) as exc:
|
|
77
|
+
raise ValueError("chart value colors must map finite numbers to supported colors") from exc
|
|
78
|
+
if not isfinite(numeric_value) or color not in BAR_COLORS:
|
|
79
|
+
raise ValueError("chart value colors must map finite numbers to supported colors")
|
|
80
|
+
parsed[numeric_value] = color
|
|
81
|
+
return parsed
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def _parse_value_labels(
|
|
85
|
+
value_labels: Optional[Mapping[float, str]],
|
|
86
|
+
) -> Optional[dict[float, str]]:
|
|
87
|
+
if value_labels is None:
|
|
88
|
+
return None
|
|
89
|
+
if not isinstance(value_labels, Mapping):
|
|
90
|
+
raise ValueError("chart value labels must map finite numbers to strings")
|
|
91
|
+
|
|
92
|
+
parsed = {}
|
|
93
|
+
for value, label in value_labels.items():
|
|
94
|
+
if isinstance(value, bool):
|
|
95
|
+
raise ValueError("chart value labels must map finite numbers to strings")
|
|
96
|
+
try:
|
|
97
|
+
numeric_value = float(value)
|
|
98
|
+
except (TypeError, ValueError) as exc:
|
|
99
|
+
raise ValueError("chart value labels must map finite numbers to strings") from exc
|
|
100
|
+
if not isfinite(numeric_value) or not isinstance(label, str):
|
|
101
|
+
raise ValueError("chart value labels must map finite numbers to strings")
|
|
102
|
+
parsed[numeric_value] = label
|
|
103
|
+
return parsed
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
def _bar_class(
|
|
107
|
+
value: float,
|
|
108
|
+
thresholds: Optional[tuple[float, float]],
|
|
109
|
+
value_colors: Optional[Mapping[float, str]],
|
|
110
|
+
) -> str:
|
|
111
|
+
if value_colors is not None:
|
|
112
|
+
color = value_colors.get(value)
|
|
113
|
+
return f"metric-bar metric-bar-{color}" if color is not None else "metric-bar"
|
|
114
|
+
if thresholds is None:
|
|
115
|
+
return "metric-bar"
|
|
116
|
+
lower, upper = thresholds
|
|
117
|
+
if value <= lower:
|
|
118
|
+
return "metric-bar metric-bar-green"
|
|
119
|
+
if value > upper:
|
|
120
|
+
return "metric-bar metric-bar-red"
|
|
121
|
+
return "metric-bar metric-bar-yellow"
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def _bar_color_name(
|
|
125
|
+
value: float,
|
|
126
|
+
thresholds: Optional[tuple[float, float]],
|
|
127
|
+
value_colors: Optional[Mapping[float, str]],
|
|
128
|
+
) -> Optional[str]:
|
|
129
|
+
if value_colors is not None:
|
|
130
|
+
return value_colors.get(value)
|
|
131
|
+
if thresholds is None:
|
|
132
|
+
return None
|
|
133
|
+
lower, upper = thresholds
|
|
134
|
+
if value <= lower:
|
|
135
|
+
return "green"
|
|
136
|
+
if value > upper:
|
|
137
|
+
return "red"
|
|
138
|
+
return "yellow"
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
def _line_class(
|
|
142
|
+
value: float,
|
|
143
|
+
thresholds: Optional[tuple[float, float]],
|
|
144
|
+
value_colors: Optional[Mapping[float, str]],
|
|
145
|
+
) -> str:
|
|
146
|
+
color = _bar_color_name(value, thresholds, value_colors)
|
|
147
|
+
return f"metric-line metric-line-{color}" if color is not None else "metric-line"
|
|
148
|
+
|
|
149
|
+
|
|
150
|
+
def _exceeds_threshold(
|
|
151
|
+
value: float,
|
|
152
|
+
thresholds: Optional[tuple[float, float]],
|
|
153
|
+
) -> bool:
|
|
154
|
+
return thresholds is not None and value > thresholds[0]
|
|
155
|
+
|
|
156
|
+
|
|
157
|
+
def _grid_offsets(length: int, spacing: int) -> range:
|
|
158
|
+
return range(0, max(0, int(length)) + 1, spacing)
|
|
159
|
+
|
|
160
|
+
|
|
161
|
+
def _draw_png(
|
|
162
|
+
output_path: Path,
|
|
163
|
+
points: Sequence[tuple[datetime, float]],
|
|
164
|
+
width: int,
|
|
165
|
+
height: int,
|
|
166
|
+
thresholds: Optional[tuple[float, float]],
|
|
167
|
+
value_colors: Optional[Mapping[float, str]],
|
|
168
|
+
value_labels: Optional[Mapping[float, str]],
|
|
169
|
+
chart_type: Literal["bar", "line"],
|
|
170
|
+
scale: int = 2,
|
|
171
|
+
) -> None:
|
|
172
|
+
from PIL import Image, ImageDraw, ImageFont
|
|
173
|
+
|
|
174
|
+
left = _LEFT * scale
|
|
175
|
+
right = _RIGHT * scale
|
|
176
|
+
top = _TOP * scale
|
|
177
|
+
bottom = _BOTTOM * scale
|
|
178
|
+
render_width = width * scale
|
|
179
|
+
render_height = height * scale
|
|
180
|
+
plot_width = render_width - left - right
|
|
181
|
+
plot_height = render_height - top - bottom
|
|
182
|
+
values = [value for _, value in points]
|
|
183
|
+
y_max = max(values, default=0.0)
|
|
184
|
+
scale_max = y_max if y_max > 0 else 1.0
|
|
185
|
+
|
|
186
|
+
img = Image.new("RGBA", (render_width, render_height), (255, 255, 255, 0))
|
|
187
|
+
draw = ImageDraw.Draw(img)
|
|
188
|
+
|
|
189
|
+
try:
|
|
190
|
+
font = ImageFont.truetype("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf", 8 * scale)
|
|
191
|
+
except OSError:
|
|
192
|
+
font = ImageFont.load_default()
|
|
193
|
+
|
|
194
|
+
start_time = points[0][0] if points else None
|
|
195
|
+
end_time = points[-1][0] if points else None
|
|
196
|
+
duration = (end_time - start_time).total_seconds() if start_time is not None and end_time is not None else 0
|
|
197
|
+
|
|
198
|
+
if value_labels:
|
|
199
|
+
for value, _label in sorted(value_labels.items()):
|
|
200
|
+
y = top + plot_height - (value / scale_max) * plot_height
|
|
201
|
+
draw.line([(left, y), (render_width - right, y)], fill=_GRID_COLOR)
|
|
202
|
+
else:
|
|
203
|
+
for offset in _grid_offsets(plot_height, _Y_GRID_SPACING * scale):
|
|
204
|
+
ratio = offset / plot_height
|
|
205
|
+
y = top + plot_height - offset
|
|
206
|
+
draw.line([(left, y), (render_width - right, y)], fill=_GRID_COLOR)
|
|
207
|
+
draw.text(
|
|
208
|
+
(left - 6 * scale, y),
|
|
209
|
+
str(round(scale_max * ratio, 2)),
|
|
210
|
+
fill=_TEXT_COLOR,
|
|
211
|
+
font=font,
|
|
212
|
+
anchor="rm",
|
|
213
|
+
)
|
|
214
|
+
|
|
215
|
+
if start_time is not None:
|
|
216
|
+
for offset in _grid_offsets(plot_width, _X_GRID_SPACING * scale):
|
|
217
|
+
ratio = offset / plot_width
|
|
218
|
+
x = left + offset
|
|
219
|
+
tick_time = start_time + timedelta(seconds=duration * ratio)
|
|
220
|
+
draw.line([(x, top), (x, top + plot_height)], fill=_GRID_COLOR)
|
|
221
|
+
draw.text(
|
|
222
|
+
(x, top + plot_height + 4 * scale),
|
|
223
|
+
tick_time.strftime("%H:%M:%S"),
|
|
224
|
+
fill=_TEXT_COLOR,
|
|
225
|
+
font=font,
|
|
226
|
+
anchor="ma",
|
|
227
|
+
)
|
|
228
|
+
|
|
229
|
+
draw.line(
|
|
230
|
+
[(left, top), (left, top + plot_height)],
|
|
231
|
+
fill=_AXIS_COLOR,
|
|
232
|
+
)
|
|
233
|
+
draw.line(
|
|
234
|
+
[(left, top + plot_height), (render_width - right, top + plot_height)],
|
|
235
|
+
fill=_AXIS_COLOR,
|
|
236
|
+
)
|
|
237
|
+
|
|
238
|
+
if not points:
|
|
239
|
+
draw.text(
|
|
240
|
+
(left + plot_width / 2, top + plot_height / 2),
|
|
241
|
+
"No data available",
|
|
242
|
+
fill=_TEXT_COLOR,
|
|
243
|
+
font=font,
|
|
244
|
+
anchor="mm",
|
|
245
|
+
)
|
|
246
|
+
img.save(output_path, "PNG")
|
|
247
|
+
return
|
|
248
|
+
|
|
249
|
+
start_time = points[0][0]
|
|
250
|
+
count = len(points)
|
|
251
|
+
coordinates = []
|
|
252
|
+
for timestamp, value in points:
|
|
253
|
+
x_ratio = (timestamp - start_time).total_seconds() / duration if duration > 0 else 0.5
|
|
254
|
+
x = left + x_ratio * plot_width
|
|
255
|
+
bar_h = (value / scale_max) * plot_height
|
|
256
|
+
y = top + plot_height - bar_h
|
|
257
|
+
coordinates.append((x, y, value))
|
|
258
|
+
|
|
259
|
+
if chart_type == "line":
|
|
260
|
+
if len(coordinates) == 1:
|
|
261
|
+
x, y, value = coordinates[0]
|
|
262
|
+
color_name = _bar_color_name(value, thresholds, value_colors)
|
|
263
|
+
color = _BAR_COLOR_HEX[color_name]
|
|
264
|
+
radius = 2 * scale
|
|
265
|
+
draw.ellipse([x - radius, y - radius, x + radius, y + radius], fill=color)
|
|
266
|
+
for previous, current in zip(coordinates, coordinates[1:]):
|
|
267
|
+
color_name = _bar_color_name(current[2], thresholds, value_colors)
|
|
268
|
+
draw.line([previous[:2], current[:2]], fill=_BAR_COLOR_HEX[color_name], width=2 * scale)
|
|
269
|
+
for x, y, value in coordinates:
|
|
270
|
+
if not _exceeds_threshold(value, thresholds):
|
|
271
|
+
continue
|
|
272
|
+
color_name = _bar_color_name(value, thresholds, value_colors)
|
|
273
|
+
radius = 3 * scale
|
|
274
|
+
draw.ellipse(
|
|
275
|
+
[x - radius, y - radius, x + radius, y + radius],
|
|
276
|
+
fill=_BAR_COLOR_HEX[color_name],
|
|
277
|
+
)
|
|
278
|
+
img.save(output_path, "PNG")
|
|
279
|
+
return
|
|
280
|
+
|
|
281
|
+
bar_width = max(1, plot_width / count - 1)
|
|
282
|
+
prev_value = None
|
|
283
|
+
for x, y, value in coordinates:
|
|
284
|
+
x = max(left + bar_width / 2, min(render_width - right - bar_width / 2, x))
|
|
285
|
+
x -= bar_width / 2
|
|
286
|
+
bar_h = top + plot_height - y
|
|
287
|
+
color_name = _bar_color_name(value, thresholds, value_colors)
|
|
288
|
+
hex_color = _BAR_COLOR_HEX[color_name]
|
|
289
|
+
draw.rectangle(
|
|
290
|
+
[x, y, x + bar_width, y + bar_h],
|
|
291
|
+
fill=hex_color,
|
|
292
|
+
)
|
|
293
|
+
if value_labels and value != prev_value:
|
|
294
|
+
label = value_labels.get(value)
|
|
295
|
+
if label:
|
|
296
|
+
draw.text(
|
|
297
|
+
(x + bar_width / 2, y - 2 * scale),
|
|
298
|
+
label,
|
|
299
|
+
fill=_TEXT_COLOR,
|
|
300
|
+
font=font,
|
|
301
|
+
anchor="ms",
|
|
302
|
+
)
|
|
303
|
+
prev_value = value
|
|
304
|
+
for x, y, value in coordinates:
|
|
305
|
+
if not _exceeds_threshold(value, thresholds):
|
|
306
|
+
continue
|
|
307
|
+
x = max(left + bar_width / 2, min(render_width - right - bar_width / 2, x))
|
|
308
|
+
color_name = _bar_color_name(value, thresholds, value_colors)
|
|
309
|
+
radius = 3 * scale
|
|
310
|
+
draw.ellipse(
|
|
311
|
+
[x - radius, y - radius, x + radius, y + radius],
|
|
312
|
+
fill=_BAR_COLOR_HEX[color_name],
|
|
313
|
+
)
|
|
314
|
+
|
|
315
|
+
img.save(output_path, "PNG")
|
|
316
|
+
|
|
317
|
+
|
|
318
|
+
def write_bar_chart(
|
|
319
|
+
output_folder: Union[Path, str],
|
|
320
|
+
metric: str,
|
|
321
|
+
points: Sequence[tuple[datetime, float]],
|
|
322
|
+
*,
|
|
323
|
+
slug: Optional[str] = None,
|
|
324
|
+
thresholds: Optional[tuple[float, float]] = None,
|
|
325
|
+
value_colors: Optional[Mapping[float, str]] = None,
|
|
326
|
+
value_labels: Optional[Mapping[float, str]] = None,
|
|
327
|
+
filename_prefix: str = "ftdc-baseline-analysis",
|
|
328
|
+
width: int = DEFAULT_CHART_WIDTH,
|
|
329
|
+
height: int = DEFAULT_CHART_HEIGHT,
|
|
330
|
+
image_format: Literal["png", "svg"] = "png",
|
|
331
|
+
chart_type: Literal["bar", "line"] = "bar",
|
|
332
|
+
) -> str:
|
|
333
|
+
"""Render a time-series chart and return its relative path.
|
|
334
|
+
|
|
335
|
+
By default the chart is saved as a PNG image. Pass ``image_format="svg"``
|
|
336
|
+
to keep the SVG source file instead.
|
|
337
|
+
"""
|
|
338
|
+
if image_format not in ("png", "svg"):
|
|
339
|
+
raise ValueError(f"unsupported image format: {image_format!r}")
|
|
340
|
+
if chart_type not in ("bar", "line"):
|
|
341
|
+
raise ValueError(f"unsupported chart type: {chart_type!r}")
|
|
342
|
+
if width <= _LEFT + _RIGHT or height <= _TOP + _BOTTOM:
|
|
343
|
+
raise ValueError("chart dimensions are too small for axes and labels")
|
|
344
|
+
output_folder = Path(output_folder)
|
|
345
|
+
if thresholds is not None and value_colors is not None:
|
|
346
|
+
raise ValueError("chart thresholds and value colors cannot be combined")
|
|
347
|
+
parsed_thresholds = _parse_thresholds(thresholds)
|
|
348
|
+
parsed_value_colors = _parse_value_colors(value_colors)
|
|
349
|
+
parsed_value_labels = _parse_value_labels(value_labels)
|
|
350
|
+
chart_folder = output_folder / "charts"
|
|
351
|
+
chart_folder.mkdir(parents=True, exist_ok=True)
|
|
352
|
+
slug = slug or re.sub(r"[^a-z0-9]+", "-", metric.lower()).strip("-")
|
|
353
|
+
relative_path = Path("charts") / f"{filename_prefix}-{slug}.{image_format}"
|
|
354
|
+
output_path = output_folder / relative_path
|
|
355
|
+
|
|
356
|
+
values = [value for _, value in points]
|
|
357
|
+
unique_values = set(values)
|
|
358
|
+
if parsed_value_labels:
|
|
359
|
+
used_labels = {v: label for v, label in sorted(parsed_value_labels.items()) if v in unique_values}
|
|
360
|
+
else:
|
|
361
|
+
used_labels = None
|
|
362
|
+
|
|
363
|
+
if image_format == "png":
|
|
364
|
+
_draw_png(output_path, points, width, height, parsed_thresholds, parsed_value_colors, used_labels, chart_type)
|
|
365
|
+
return relative_path.as_posix()
|
|
366
|
+
|
|
367
|
+
left, right, top, bottom = _LEFT, _RIGHT, _TOP, _BOTTOM
|
|
368
|
+
plot_width = width - left - right
|
|
369
|
+
plot_height = height - top - bottom
|
|
370
|
+
values = [value for _, value in points]
|
|
371
|
+
y_max = max(values, default=0.0)
|
|
372
|
+
scale_max = y_max if y_max > 0 else 1.0
|
|
373
|
+
|
|
374
|
+
marks = ""
|
|
375
|
+
if points:
|
|
376
|
+
start_time = points[0][0]
|
|
377
|
+
end_time = points[-1][0]
|
|
378
|
+
duration = (end_time - start_time).total_seconds()
|
|
379
|
+
coordinates = []
|
|
380
|
+
for timestamp, value in points:
|
|
381
|
+
x_ratio = (timestamp - start_time).total_seconds() / duration if duration > 0 else 0.5
|
|
382
|
+
x = left + x_ratio * plot_width
|
|
383
|
+
bar_h = (value / scale_max) * plot_height
|
|
384
|
+
y = top + plot_height - bar_h
|
|
385
|
+
coordinates.append((x, y, value))
|
|
386
|
+
if chart_type == "line":
|
|
387
|
+
if len(coordinates) == 1:
|
|
388
|
+
x, y, value = coordinates[0]
|
|
389
|
+
marks = f'<circle class="{_line_class(value, parsed_thresholds, parsed_value_colors)}" '
|
|
390
|
+
marks += f'cx="{x:.2f}" cy="{y:.2f}" r="2"/>'
|
|
391
|
+
else:
|
|
392
|
+
for previous, current in zip(coordinates, coordinates[1:]):
|
|
393
|
+
line_class = _line_class(current[2], parsed_thresholds, parsed_value_colors)
|
|
394
|
+
marks += (
|
|
395
|
+
f'<line class="{line_class}" x1="{previous[0]:.2f}" y1="{previous[1]:.2f}" '
|
|
396
|
+
f'x2="{current[0]:.2f}" y2="{current[1]:.2f}"/>'
|
|
397
|
+
)
|
|
398
|
+
for x, y, value in coordinates:
|
|
399
|
+
if not _exceeds_threshold(value, parsed_thresholds):
|
|
400
|
+
continue
|
|
401
|
+
color_name = _bar_color_name(value, parsed_thresholds, parsed_value_colors)
|
|
402
|
+
marks += (
|
|
403
|
+
f'<circle class="metric-threshold-point metric-threshold-point-{color_name}" '
|
|
404
|
+
f'cx="{x:.2f}" cy="{y:.2f}" r="3"/>'
|
|
405
|
+
)
|
|
406
|
+
else:
|
|
407
|
+
count = len(points)
|
|
408
|
+
bar_width = max(1, plot_width / count - 1)
|
|
409
|
+
prev_value = None
|
|
410
|
+
for x, y, value in coordinates:
|
|
411
|
+
x = max(left + bar_width / 2, min(width - right - bar_width / 2, x))
|
|
412
|
+
x -= bar_width / 2
|
|
413
|
+
bar_h = top + plot_height - y
|
|
414
|
+
bar_class = _bar_class(value, parsed_thresholds, parsed_value_colors)
|
|
415
|
+
marks += (
|
|
416
|
+
f'<rect class="{bar_class}" x="{x:.2f}" y="{y:.2f}" width="{bar_width:.2f}" height="{bar_h:.2f}"/>'
|
|
417
|
+
)
|
|
418
|
+
if used_labels and value != prev_value:
|
|
419
|
+
label = used_labels.get(value)
|
|
420
|
+
if label:
|
|
421
|
+
marks += (
|
|
422
|
+
f'<text class="metric-y-label" x="{x + bar_width / 2:.2f}" '
|
|
423
|
+
f'y="{y - 4:.2f}" text-anchor="middle">{label}</text>'
|
|
424
|
+
)
|
|
425
|
+
prev_value = value
|
|
426
|
+
for x, y, value in coordinates:
|
|
427
|
+
if not _exceeds_threshold(value, parsed_thresholds):
|
|
428
|
+
continue
|
|
429
|
+
x = max(left + bar_width / 2, min(width - right - bar_width / 2, x))
|
|
430
|
+
color_name = _bar_color_name(value, parsed_thresholds, parsed_value_colors)
|
|
431
|
+
marks += (
|
|
432
|
+
f'<circle class="metric-threshold-point metric-threshold-point-{color_name}" '
|
|
433
|
+
f'cx="{x:.2f}" cy="{y:.2f}" r="3"/>'
|
|
434
|
+
)
|
|
435
|
+
else:
|
|
436
|
+
marks = (
|
|
437
|
+
f'<text x="{left + plot_width / 2:.2f}" y="{top + plot_height / 2:.2f}" '
|
|
438
|
+
'text-anchor="middle">No data available</text>'
|
|
439
|
+
)
|
|
440
|
+
|
|
441
|
+
grid = ""
|
|
442
|
+
start_time = points[0][0] if points else None
|
|
443
|
+
end_time = points[-1][0] if points else None
|
|
444
|
+
duration = (end_time - start_time).total_seconds() if start_time is not None and end_time is not None else 0
|
|
445
|
+
if used_labels:
|
|
446
|
+
for value, _label in used_labels.items():
|
|
447
|
+
y = top + plot_height - (value / scale_max) * plot_height
|
|
448
|
+
grid += f'<line class="metric-grid" x1="{left}" y1="{y:.2f}" x2="{width - right}" y2="{y:.2f}"/>'
|
|
449
|
+
else:
|
|
450
|
+
for offset in _grid_offsets(plot_height, _Y_GRID_SPACING):
|
|
451
|
+
ratio = offset / plot_height
|
|
452
|
+
y = top + plot_height - offset
|
|
453
|
+
grid += f'<line class="metric-grid" x1="{left}" y1="{y:.2f}" x2="{width - right}" y2="{y:.2f}"/>'
|
|
454
|
+
label_text = str(round(scale_max * ratio, 2))
|
|
455
|
+
grid += f'<text class="metric-y-label" x="{left - 6}" y="{y + 3:.2f}" text-anchor="end">{label_text}</text>'
|
|
456
|
+
|
|
457
|
+
if start_time is not None:
|
|
458
|
+
for offset in _grid_offsets(plot_width, _X_GRID_SPACING):
|
|
459
|
+
ratio = offset / plot_width
|
|
460
|
+
x = left + offset
|
|
461
|
+
tick_time = start_time + timedelta(seconds=duration * ratio)
|
|
462
|
+
grid += f'<line class="metric-grid" x1="{x:.2f}" y1="{top}" x2="{x:.2f}" y2="{top + plot_height}"/>'
|
|
463
|
+
grid += (
|
|
464
|
+
f'<text class="metric-x-label" x="{x:.2f}" y="{top + plot_height + 12}" '
|
|
465
|
+
f'text-anchor="middle">{tick_time.strftime("%H:%M:%S")}</text>'
|
|
466
|
+
)
|
|
467
|
+
|
|
468
|
+
svg = (
|
|
469
|
+
f'<svg xmlns="http://www.w3.org/2000/svg" width="{width}" height="{height}" '
|
|
470
|
+
f'viewBox="0 0 {width} {height}" role="img" aria-label="{escape(metric)} {chart_type} chart">'
|
|
471
|
+
"<style>"
|
|
472
|
+
"text{font:9px sans-serif;fill:#57606a}"
|
|
473
|
+
f".metric-bar{{fill:{_BAR_COLOR_HEX[None]}}}"
|
|
474
|
+
f".metric-bar-green{{fill:{_BAR_COLOR_HEX['green']}}}"
|
|
475
|
+
f".metric-bar-yellow{{fill:{_BAR_COLOR_HEX['yellow']}}}"
|
|
476
|
+
f".metric-bar-red{{fill:{_BAR_COLOR_HEX['red']}}}"
|
|
477
|
+
f".metric-bar-blue{{fill:{_BAR_COLOR_HEX['blue']}}}"
|
|
478
|
+
f".metric-bar-gray{{fill:{_BAR_COLOR_HEX['gray']}}}"
|
|
479
|
+
f".metric-line{{fill:{_BAR_COLOR_HEX[None]};stroke:{_BAR_COLOR_HEX[None]};stroke-width:2}}"
|
|
480
|
+
f".metric-line-green{{fill:{_BAR_COLOR_HEX['green']};stroke:{_BAR_COLOR_HEX['green']}}}"
|
|
481
|
+
f".metric-line-yellow{{fill:{_BAR_COLOR_HEX['yellow']};stroke:{_BAR_COLOR_HEX['yellow']}}}"
|
|
482
|
+
f".metric-line-red{{fill:{_BAR_COLOR_HEX['red']};stroke:{_BAR_COLOR_HEX['red']}}}"
|
|
483
|
+
f".metric-line-blue{{fill:{_BAR_COLOR_HEX['blue']};stroke:{_BAR_COLOR_HEX['blue']}}}"
|
|
484
|
+
f".metric-line-gray{{fill:{_BAR_COLOR_HEX['gray']};stroke:{_BAR_COLOR_HEX['gray']}}}"
|
|
485
|
+
f".metric-threshold-point{{fill:{_BAR_COLOR_HEX[None]}}}"
|
|
486
|
+
f".metric-threshold-point-green{{fill:{_BAR_COLOR_HEX['green']}}}"
|
|
487
|
+
f".metric-threshold-point-yellow{{fill:{_BAR_COLOR_HEX['yellow']}}}"
|
|
488
|
+
f".metric-threshold-point-red{{fill:{_BAR_COLOR_HEX['red']}}}"
|
|
489
|
+
f".metric-threshold-point-blue{{fill:{_BAR_COLOR_HEX['blue']}}}"
|
|
490
|
+
f".metric-threshold-point-gray{{fill:{_BAR_COLOR_HEX['gray']}}}"
|
|
491
|
+
".metric-grid{stroke:#d0d7de;stroke-width:1}"
|
|
492
|
+
"</style>"
|
|
493
|
+
f"{grid}"
|
|
494
|
+
f'<line x1="{left}" y1="{top}" x2="{left}" y2="{top + plot_height}" stroke="#8c959f"/>'
|
|
495
|
+
f'<line x1="{left}" y1="{top + plot_height}" x2="{width - right}" '
|
|
496
|
+
f'y2="{top + plot_height}" stroke="#8c959f"/>'
|
|
497
|
+
f"{marks}</svg>"
|
|
498
|
+
)
|
|
499
|
+
output_path.write_text(svg, encoding="utf-8")
|
|
500
|
+
return relative_path.as_posix()
|