### Structured Logging in PerfSpect
Source: https://github.com/intel/perfspect/blob/main/CONTRIBUTING.md
Examples of using `log/slog` for structured logging in PerfSpect, covering different log levels.
```go
slog.Debug("detailed info for debugging", slog.String("key", value))
```
```go
slog.Info("normal operation info")
```
```go
slog.Warn("potential issue", slog.String("reason", reason))
```
```go
slog.Error("operation failed", slog.String("error", err.Error()))
```
--------------------------------
### PerfSpect Help Command
Source: https://github.com/intel/perfspect/blob/main/docs/perfspect.md
To get more information about a specific command, use the --help flag with the command name. This provides detailed usage instructions and available options for that command.
```bash
perfspect [command] --help
```
--------------------------------
### Add New Command to PerfSpect
Source: https://github.com/intel/perfspect/blob/main/CONTRIBUTING.md
Example Go code for adding a new command to PerfSpect, including registration and defining tables.
```go
package yourcommand
import (
"perfspect/internal/workflow"
"perfspect/internal/table"
"github.com/spf13/cobra"
)
var Cmd = &cobra.Command{
GroupID: "primary",
Use: "yourcommand",
Short: "Description of your command",
RunE: runYourCommand,
}
func init() {
// Add command-specific flags here
workflow.AddTargetFlags(Cmd)
workflow.AddFormatFlag(Cmd)
}
func runYourCommand(cmd *cobra.Command, args []string) error {
rc := workflow.ReportingCommand{
Cmd: cmd,
Tables: yourTables, // Define tables for data collection
}
return rc.Run()
}
var yourTables = []table.TableDefinition{
// Define what data to collect
}
```
```go
import "perfspect/cmd/yourcommand"
func init() {
// ...
rootCmd.AddCommand(yourcommand.Cmd)
}
```
--------------------------------
### PerfSpect Command Usage
Source: https://github.com/intel/perfspect/blob/main/README.md
This is the general usage format for the PerfSpect command-line tool. Use this as a starting point for exploring its various commands and options.
```text
Usage:
perfspect [command] [flags]
```
--------------------------------
### Target Multiple Remote Hosts with YAML
Source: https://github.com/intel/perfspect/blob/main/README.md
To target multiple remote systems, provide a YAML file containing connection parameters to the --targets flag. Refer to the example targets.yaml file for structure.
```text
./perfspect report --targets mytargets.yaml
```
--------------------------------
### Base Line Chart Configuration
Source: https://github.com/intel/perfspect/blob/main/cmd/metrics/resources/base.html
Defines the common configuration for all line charts, including axis types, data ranges, and tooltip settings. Ensures charts start at the first data point and labels are rotated for readability.
```javascript
const base_line = {
xAxis: {
type: "category",
data: <<.TIMESTAMPS>>,
min: "dataMin",
max: "dataMax",
boundaryGap: false, // ensure the chart starts at the first data point
axisLabel: {
rotate: 45,
}
},
yAxis: {},
tooltip: {
trigger: 'axis',
valueFormatter: (value) => value.toFixed(2),
},
legend: {
orient: 'horizontal',
top: 20,
left: 'center',
show: true,
selectedMode: false, // Prevents toggling series visibility by clicking on legend
},
}
```
--------------------------------
### Run Performance Micro-benchmarks
Source: https://github.com/intel/perfspect/blob/main/README.md
Execute performance micro-benchmarks with the 'benchmark' command. Run all benchmarks by default, or specify individual benchmarks using flags like --speed and --power. Use --no-summary to exclude the system summary.
```bash
./perfspect benchmark # Run all benchmarks with system summary
```
```bash
./perfspect benchmark --speed --power # Run specific benchmarks
```
```bash
./perfspect benchmark --no-summary # Exclude system summary from output
```
--------------------------------
### Configure System Cores and Cache
Source: https://github.com/intel/perfspect/blob/main/README.md
Use the config command to set the number of cores, LLC, and uncore frequency. Ensure correct parameters are used to avoid system instability.
```text
$ ./perfspect config --cores 24 --llc 2.0 --uncore-max 1.8
...
```
--------------------------------
### Record and Restore Configuration
Source: https://github.com/intel/perfspect/blob/main/docs/perfspect_config.md
Records the current system configuration to a file before making changes, allowing for later restoration. Use the 'restore' subcommand with the recorded file to revert settings.
```bash
$ perfspect config --c6 disable --epb 0 --record
```
```bash
$ perfspect config restore gnr_config.txt
```
--------------------------------
### Build PerfSpect
Source: https://github.com/intel/perfspect/blob/main/CONTRIBUTING.md
Use these commands to build the PerfSpect project. The complete build requires Docker.
```bash
builder/build.sh
```
```bash
make
```
```bash
make check
```
--------------------------------
### Configure Sunburst Chart for TMA Categories
Source: https://github.com/intel/perfspect/blob/main/cmd/metrics/resources/base.html
Defines the configuration for a sunburst chart, including colors for different TMA categories and their child variations. This setup is used for visualizing hierarchical data.
```javascript
const tmaColors = {
// Blue family for Frontend
'Frontend': '#4472c4',
'FrontendChild': '#7293d3',
// Lighter blue for all Frontend children
// Green family for Retiring
'Retiring': '#70ad47',
'RetiringChild': '#9bc56e',
// Lighter green for all Retiring children
// Orange family for BadSpeculation
'BadSpeculation': '#ff8c42',
'BadSpeculationChild': '#ffab73',
// Lighter orange for all BadSpeculation children
// Teal family for Backend
'Backend': '#2e8b8b',
'BackendChild': '#5ba3a3'
// Lighter teal for all Backend children
};
let tmasunburst = {
tooltip: {},
color: [tmaColors.Frontend, tmaColors.BadSpeculation, tmaColors.Backend, tmaColors.Retiring],
series: {
nodeClick: false,
type: "sunburst",
radius: [60, "90%"],
itemStyle: {
borderRadius: 7,
borderWidth: 2,
},
data: [
{
name: "<<.FRONTEND_LABEL>>",
value: Math.round(<<.FRONTEND >> * 10) / 10,
itemStyle: {
color: tmaColors.Frontend
},
children: [
{
name: "<<.FETCHBANDWIDTH_LABEL>>",
value: Math.round(<<.FETCHBANDWIDTH >> * 10) / 10,
itemStyle: {
color: tmaColors.FrontendChild
}
},
{
name: "<<.FETCHLATENCY_LABEL>>",
value: Math.round(<<.FETCHLATENCY >> * 10) / 10,
itemStyle: {
color: tmaColors.FrontendChild
}
},
]
},
{
name: "<<.BADSPECULATION_LABEL>>",
value: Math.round(<<.BADSPECULATION >> * 10) / 10,
itemStyle: {
color: tmaColors.BadSpeculation
},
children: [
{
name: "<<.BRANCHMISPREDICTS_LABEL>>",
value: Math.round(<<.BRANCHMISPREDICTS >> * 10) / 10,
itemStyle: {
color: tmaColors.BadSpeculationChild
}
},
{
name: "<<.MACHINECLEARS_LABEL>>",
value: Math.round(<<.MACHINECLEARS >> * 10) / 10,
itemStyle: {
color: tmaColors.BadSpeculationChild
}
},
]
},
{
name: "<<.BACKEND_LABEL>>",
value: Math.round(<<.BACKEND >> * 10) / 10,
itemStyle: {
color: tmaColors.Backend
},
children: [
{
name: "<<.CORE_LABEL>>",
value: Math.round(<<.COREDATA >> * 10) / 10,
itemStyle: {
color: tmaColors.BackendChild
}
},
{
name: "<<.MEMORY_LABEL>>",
value: Math.round(<<.MEMORY >> * 10) / 10,
itemStyle: {
color: tmaColors.BackendChild
}
},
],
},
{
name: "<<.RETIRING_LABEL>>",
value: Math.round(<<.RETIRING >> * 10) / 10,
itemStyle: {
color: tmaColors.Retiring
},
ch
```
--------------------------------
### Generate System Configuration Report
Source: https://github.com/intel/perfspect/blob/main/README.md
Generate system configuration reports using the 'report' command. Specify the format and categories of information to include. The 'txt' format prints to stdout and a file.
```bash
$ ./perfspect report --bios --format txt
```
--------------------------------
### Reporting Command Signal Handling Architecture
Source: https://github.com/intel/perfspect/blob/main/docs/signal-handling.md
Illustrates the architecture for signal handling in reporting commands, showing the Go application, its signal handler goroutine, and the controller scripts running on targets in their own process groups.
```text
perfspect (Go)
┌─────────────────────────────────────────────┐
│ signal handler goroutine │
│ (configureSignalHandler) │
│ │
│ Listens for SIGINT / SIGTERM │
└──────────┬──────────────────────────────────┘
│
┌───────────────────┼───────────────────┐
▼ ▼ ▼
Target A Target B Target N
┌──────────┐ ┌──────────┐ ┌──────────┐
│controller│ │controller│ │controller│
│ .sh │ │ .sh │ │ .sh │
│(own PGID)│ │(own PGID)│ │(own PGID)│
└────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │
┌────┴────┐ ┌────┴────┐ ┌────┴────┐
│ scripts │ │ scripts │ │ scripts │
│(setsid) │ │(setsid) │ │(setsid) │
└─────────┘ └─────────┘ └─────────┘
```
--------------------------------
### Run PerfSpect Metrics Command
Source: https://github.com/intel/perfspect/blob/main/README.md
Execute the 'metrics' command to generate CPU architectural performance characterization metrics. Reports are saved in HTML and CSV formats by default.
```bash
perfspect metrics
```
--------------------------------
### Trim Metrics Using Absolute Timestamps and Specific CSV
Source: https://github.com/intel/perfspect/blob/main/docs/perfspect_metrics_trim.md
Use this command to filter metrics within a precise time window defined by absolute start and end timestamps. You can also specify a particular CSV file within the input directory.
```bash
$ perfspect metrics trim --input perfspect_2025-11-28_09-21-56/myhost_metrics.csv --start-time 1764174327 --end-time 1764174351
```
--------------------------------
### Run Unit Tests and Code Quality Checks
Source: https://github.com/intel/perfspect/blob/main/ARCHITECTURE.md
Commands to execute unit tests and comprehensive code quality checks, including formatting, vetting, and linting.
```bash
make test
```
```bash
make check
```
--------------------------------
### Set Multiple Config Items on Local Host
Source: https://github.com/intel/perfspect/blob/main/docs/perfspect_config.md
Configures multiple system parameters simultaneously on the local host, including maximum core frequency, uncore frequency, and TDP. Ensure all specified values are valid for the target system.
```bash
$ perfspect config --core-max 3.0 --uncore-max 2.1 --tdp 120
```
--------------------------------
### Run PerfSpect Metrics Command in Live Mode
Source: https://github.com/intel/perfspect/blob/main/README.md
Use the '--live' flag with the 'metrics' command to stream performance metrics directly to standard output. This is useful for real-time monitoring or piping data to other tools.
```bash
perfspect metrics --live
```
--------------------------------
### Record System Configuration
Source: https://github.com/intel/perfspect/blob/main/README.md
Save the current system configuration to a file for later restoration. This is useful for backing up settings or applying them to other systems.
```text
$ ./perfspect config --tdp 300 --record
Configuration recorded to: perfspect_2025-12-01_14-30-45/gnr_config.txt
```
--------------------------------
### Build PerfSpect Distribution
Source: https://github.com/intel/perfspect/blob/main/builder/README.md
Execute the main build script from the repository root. To force a rebuild of tools and skip caching, set the SKIP_TOOLS_CACHE environment variable.
```bash
# Build from the repository root
./builder/build.sh
```
```bash
# Force rebuild of tools (skip cache)
SKIP_TOOLS_CACHE=1 ./builder/build.sh
```
--------------------------------
### Restore System Configuration
Source: https://github.com/intel/perfspect/blob/main/README.md
Restore system configuration from a previously recorded file. This command prompts for confirmation before applying changes, which can be bypassed with the --yes flag.
```text
$ ./perfspect config restore perfspect_2025-12-01_14-30-45/gnr_config.txt
Configuration settings to restore from perfspect_2025-12-01_14-30-45/gnr_config.txt:
Cores per Socket : 86
L3 Cache : 336
Package Power / TDP : 350
...
Apply these configuration changes? [y/N]: y
...
```
```text
./perfspect config restore perfspect_2025-12-01_14-30-45/gnr_config.txt --yes
```
--------------------------------
### Generate Configuration Report
Source: https://github.com/intel/perfspect/blob/main/docs/perfspect.md
Use the 'report' command to collect configuration data from local or remote targets. Specify remote targets using --target, --targets, --user, and --key flags.
```bash
$ perfspect report
```
```bash
$ perfspect report --target 192.168.1.2 --user elaine --key ~/.ssh/id_rsa
```
```bash
$ perfspect report --targets ./targets.yaml
```
--------------------------------
### Collect Micro-architectural Metrics
Source: https://github.com/intel/perfspect/blob/main/docs/perfspect.md
Use the 'metrics' command to collect micro-architectural performance metrics from target systems. This command is useful for in-depth performance analysis.
```bash
$ perfspect metrics
```
--------------------------------
### Run PerfSpect Metrics Command Without Root
Source: https://github.com/intel/perfspect/blob/main/README.md
If root permissions are unavailable, use the '--noroot' flag with the 'metrics' command after applying specific system configurations. Ensure 'kernel.perf_event_paranoid' and 'kernel.nmi_watchdog' are set appropriately, and 'perf_event_mux_interval_ms' is configured.
```bash
perfspect metrics --noroot
```
--------------------------------
### Memory Bandwidth Chart Configuration
Source: https://github.com/intel/perfspect/blob/main/cmd/metrics/resources/base.html
Configures the Memory bandwidth chart using the base line chart configuration. Displays Read, Write, and Total memory bandwidth metrics.
```javascript
let memory = {
...base_line,
series: [
{
name: "Read",
type: 'line',
data: <<.READDATA>>,
},
{
name: "Write",
type: 'line',
data: <<.WRITEDATA>>,
},
{
name: "Total",
type: 'line',
data: <<.TOTALDATA>>,
},
],
}
```
--------------------------------
### CPU Utilization Chart Configuration
Source: https://github.com/intel/perfspect/blob/main/cmd/metrics/resources/base.html
Configures the CPU Utilization chart using the base line chart configuration. Displays the 'CPU Utilization %' metric.
```javascript
let cpu_util = {
...base_line,
series: [
{
name: "CPU Utilization %",
type: 'line',
data: <<.CPUUTIL>>,
},
],
}
```
--------------------------------
### Run PerfSpect Report Command
Source: https://github.com/intel/perfspect/blob/main/ARCHITECTURE.md
Initiates a performance report generation for a remote target. Requires target address, username, and SSH key.
```bash
perfspect report --target 192.168.1.2 --user admin --key ~/.ssh/id_rsa
```
--------------------------------
### Kernel Utilization Chart Configuration
Source: https://github.com/intel/perfspect/blob/main/cmd/metrics/resources/base.html
Configures the Kernel Utilization chart using the base line chart configuration. Displays the 'Kernel Utilization %' metric.
```javascript
let kernel_util = {
...base_line,
series: [
{
name: "Kernel Utilization %",
type: 'line',
data: <<.KERNELUTIL>>,
},
],
}
```
--------------------------------
### Package Power Chart Configuration
Source: https://github.com/intel/perfspect/blob/main/cmd/metrics/resources/base.html
Configures the Package Power chart using the base line chart configuration. Displays the 'Package Power (Watts)' metric.
```javascript
let package_power = {
...base_line,
series: [
{
name: "Package Power (Watts)",
type: 'line',
data: <<.PKGPOWER>>,
},
],
}
```
--------------------------------
### Run PerfSpect Tests
Source: https://github.com/intel/perfspect/blob/main/CONTRIBUTING.md
Commands for running tests in PerfSpect. Includes running all tests, specific tests, and local or remote testing.
```bash
# Run all tests
make test
```
```bash
# Run specific test
go test -v ./internal/extract/... -run TestName
```
```bash
# Test locally
./perfspect report
```
```bash
# Test with a remote target
./perfspect report --target hostname --user username --key ~/.ssh/id_rsa
```
--------------------------------
### Add Metrics for New CPU in PerfSpect
Source: https://github.com/intel/perfspect/blob/main/CONTRIBUTING.md
Go code snippets for adding metrics for a new CPU architecture in PerfSpect, including defining constants and detection logic.
```go
const UarchYourCPU = "YourCPU"
```
--------------------------------
### PerfSpect DaemonSet and PodMonitoring Configuration
Source: https://github.com/intel/perfspect/blob/main/docs/perfspect-daemonset.md
This YAML defines a DaemonSet to run the PerfSpect container and a PodMonitoring resource to scrape its metrics. Ensure you replace the image path with your actual container image location. The DaemonSet runs PerfSpect with specific arguments for metrics collection, and the PodMonitoring targets the exposed metrics port.
```yaml
apiVersion: apps/v1
kind: DaemonSet
metadata:
name: perfspect
namespace: default
labels:
name: perfspect
spec:
selector:
matchLabels:
name: perfspect
template:
metadata:
labels:
name: perfspect
spec:
containers:
- name: perfspect
image: docker.registry/user-sandbox/ar-us/perfspect
imagePullPolicy: Always
securityContext:
privileged: true
args:
- "/perfspect"
- "metrics"
- "--log-stdout"
- "--granularity"
- "cpu"
- "--noroot"
- "--interval"
- "15"
- "--prometheus-server-addr"
- ":9090"
ports:
- name: metrics-port # Name of the port, referenced by PodMonitoring
containerPort: 9090 # The port your application inside the container listens on for metrics
protocol: TCP
resources:
requests:
memory: "200Mi"
cpu: "500m"
---
apiVersion: monitoring.googleapis.com/v1
kind: PodMonitoring
metadata:
name: perfspect-podmonitoring
namespace: default
labels:
name: perfspect
spec:
selector:
matchLabels:
name: perfspect
endpoints:
- port: metrics-port
interval: 30s
```
--------------------------------
### Enable Syslog for Logging
Source: https://github.com/intel/perfspect/blob/main/README.md
Direct PerfSpect logs to the local system's syslog daemon instead of the default log file (perfspect.log) by using the --syslog flag.
```text
./perfspect metrics --syslog
```
--------------------------------
### CPU Frequency Chart Configuration
Source: https://github.com/intel/perfspect/blob/main/cmd/metrics/resources/base.html
Configures the CPU Frequency chart using the base line chart configuration. Displays the 'CPU Frequency (GHz)' metric.
```javascript
let cpu_freq = {
...base_line,
series: [
{
name: "CPU Frequency (GHz)",
type: 'line',
data: <<.CPUFREQ>>,
},
],
}
```
--------------------------------
### Download and Extract PerfSpect
Source: https://github.com/intel/perfspect/blob/main/README.md
Use this command to download the latest release of PerfSpect and extract it to the current directory. Navigate into the extracted 'perfspect' directory to begin using the tool.
```text
wget -qO- https://github.com/intel/PerfSpect/releases/latest/download/perfspect.tgz | tar -xvz
cd perfspect
```
--------------------------------
### C6 Core Residency Chart Configuration
Source: https://github.com/intel/perfspect/blob/main/cmd/metrics/resources/base.html
Configures the C6 Core Residency chart using the base line chart configuration. Displays the 'Core C6 Residency %' metric.
```javascript
let c6_core = {
...base_line,
series: [
{
name: "Core C6 Residency %",
type: 'line',
data: <<.C6CORE>>,
},
],
}
```
--------------------------------
### View Current Configuration on Remote Target
Source: https://github.com/intel/perfspect/blob/main/docs/perfspect_config.md
Retrieves and displays the current system configuration from a remote target via SSH. Requires target IP, username, and SSH key.
```bash
$ perfspect config --target 192.168.1.1 --user fred --key fred_key
```
--------------------------------
### DRAM Power Chart Configuration
Source: https://github.com/intel/perfspect/blob/main/cmd/metrics/resources/base.html
Configures the DRAM Power chart using the base line chart configuration. Displays the 'DRAM Power (Watts)' metric.
```javascript
let dram_power = {
...base_line,
series: [
{
name: "DRAM Power (Watts)",
type: 'line',
data: <<.DRAMPOWER>>,
},
],
}
```
--------------------------------
### Set Configuration on Remote Target
Source: https://github.com/intel/perfspect/blob/main/docs/perfspect_config.md
Applies configuration settings to a remote target system using SSH. Specify the target's IP address, username, and SSH key for connection.
```bash
$ perfspect config --cores 32 --target 192.168.1.1 --user fred --key fred_key
```
--------------------------------
### CPI Chart Configuration
Source: https://github.com/intel/perfspect/blob/main/cmd/metrics/resources/base.html
Configures the Cycles Per Instruction (CPI) chart using the base line chart configuration. Displays the 'CPI' metric.
```javascript
let cpi = {
...base_line,
series: [
{
name: "CPI",
type: 'line',
data: <<.CPIDATA>>,
},
],
}
```
--------------------------------
### Target Interface Definition
Source: https://github.com/intel/perfspect/blob/main/ARCHITECTURE.md
Defines the interface for interacting with local or remote systems, abstracting differences for data collection.
```go
type Target interface {
CanConnect() bool
RunCommand(cmd *exec.Cmd) (stdout, stderr string, exitCode int, err error)
RunCommandEx(cmd *exec.Cmd, timeout int, newProcessGroup bool, reuseSSH bool) (...)
PushFile(srcPath, dstPath string) error
PullFile(srcPath, dstDir string) error
CreateTempDirectory(rootDir string) (string, error)
// ... additional methods for privilege elevation, architecture detection, etc.
}
```
--------------------------------
### Specify Custom Output Directory
Source: https://github.com/intel/perfspect/blob/main/README.md
Use the --output flag to specify a custom directory for PerfSpect to store output files, overriding the default behavior of creating a unique directory in the current working directory.
```text
./perfspect telemetry --output /home/elaine/perfspect/telemetry
```
--------------------------------
### Signal Handling Logic (Go)
Source: https://github.com/intel/perfspect/blob/main/docs/signal-handling.md
This function is responsible for signaling a process on a target machine, potentially opening a new SSH session for remote targets. It includes a wait time to account for network latency and remote process grace periods.
```go
func signalProcessOnTarget(t Target, pid int, sig syscall.Signal, waitTime time.Duration) error {
return t.RunCommandEx(fmt.Sprintf("kill -%s %d", sig.String(), pid), waitTime)
}
```
--------------------------------
### SSH Exit Code Handling (Go)
Source: https://github.com/intel/perfspect/blob/main/docs/signal-handling.md
This code demonstrates how to parse output from a remote command executed via SSH. It checks for a specific delimiter to determine if usable output exists, allowing processing of results even if the SSH command returns a non-zero exit code (like 255).
```go
// The SSH exit code is 255 if the connection is interrupted.
// We check for the delimiter to determine if usable output exists.
```
--------------------------------
### ReportingCommand Struct
Source: https://github.com/intel/perfspect/blob/main/ARCHITECTURE.md
Encapsulates the common workflow for commands like report, telemetry, flamegraph, and lock, including data collection and reporting steps.
```go
type ReportingCommand struct {
Cmd *cobra.Command
Tables []table.TableDefinition // What data to collect
ScriptParams map[string]string // Parameters for scripts
SummaryFunc SummaryFunc // Optional: build summary from collected data
InsightsFunc InsightsFunc // Optional: generate insights/recommendations
AdhocFunc AdhocFunc // Optional: post-collection actions
}
```
--------------------------------
### Define a New Script in PerfSpect
Source: https://github.com/intel/perfspect/blob/main/CONTRIBUTING.md
Go code structure for defining a new script in PerfSpect, including its name, template, and execution properties.
```go
var YourScript = ScriptDefinition{
Name: YourScriptName,
ScriptTemplate: `# Your script content
echo "output"
`,
Superuser: false, // true if requires root
Sequential: false, // true if must run alone
Depends: []string{}, // binary dependencies
}
```
--------------------------------
### Create Material-UI Theme
Source: https://github.com/intel/perfspect/blob/main/cmd/metrics/resources/base.html
Creates a Material-UI theme instance with custom typography settings, including font size and font family definitions. This theme is applied globally to the application.
```javascript
const { colors, CssBaseline, ThemeProvider, Container, createTheme, Typography, Button, IconButton, ButtonGroup, Slider, Grid, Box, Tab, Dialog, Alert, Snackbar, Link, Tabs, TextField, Icon, Table, TableBody, TableCell, TableContainer, TableHead, TableRow, Tooltip, Paper, } = MaterialUI; // Create a theme instance. const theme = createTheme({
typography: {
fontSize: 14,
h2: {
fontSize: "2.5rem",
},
fontFamily: [
"-apple-system",
"BlinkMacSystemFont",
'"Segoe UI"',
"Roboto",
'"Helvetica Neue"',
"Arial",
"sans-serif",
'"Apple Color Emoji"',
'"Segoe UI Emoji"',
'"Segoe UI Symbol"',
].join(","),
},
palette: {
mode: 'light',
},
});
```
--------------------------------
### Enable Prometheus Metrics Endpoint
Source: https://github.com/intel/perfspect/blob/main/README.md
Expose metrics via a Prometheus compatible endpoint using the '--prometheus-server' flag. The default port is 9090, which can be changed with '--prometheus-server-addr'.
```bash
perfspect metrics --prometheus-server
```
--------------------------------
### Cache Metrics Chart Configuration
Source: https://github.com/intel/perfspect/blob/main/cmd/metrics/resources/base.html
Configures the Cache metrics chart using the base line chart configuration. Displays L1D, L2, and LLC Data cache metrics.
```javascript
let cache = {
...base_line,
series: [
{
name: "L1D",
type: 'line',
data: <<.L1DATA>>,
},
{
name: "L2",
type: 'line',
data: <<.L2DATA>>,
},
{
name: "LLC Data",
type: 'line',
data: <<.LLCDATA>>,
},
],
}
```
--------------------------------
### Trim Metrics by Skipping First 10 and Last 5 Seconds
Source: https://github.com/intel/perfspect/blob/main/docs/perfspect_metrics_trim.md
Use this command to exclude both the initial 10 seconds and the final 5 seconds of metric data. Specify the input directory or file path.
```bash
$ perfspect metrics trim --input perfspect_2025-11-28_09-21-56 --start-offset 10 --end-offset 5
```
--------------------------------
### Loader Interface Definition
Source: https://github.com/intel/perfspect/blob/main/ARCHITECTURE.md
Defines the interface for loading metric definitions, supporting different formats across CPU architectures.
```go
type Loader interface {
Load(config LoaderConfig) (metrics []MetricDefinition, groups []GroupDefinition, err error)
}
```
--------------------------------
### Diff Report File Comparison Logic
Source: https://github.com/intel/perfspect/blob/main/cmd/metrics/resources/base.html
Handles file input for comparing performance metrics. Parses a selected file, extracts metric data, calculates differences, and updates the UI state with max/min differences and current metrics.
```javascript
const diffreport = (e) => {
let reader = new FileReader();
reader.onload = (e) => {
let new_metrics = JSON.parse(e.target.result.split("\n").filter(e => e.includes("const all_metrics ="))[0].split("const all_metrics =")[1])
let copy = JSON.parse(JSON.stringify(current_metrics))
let temp_mindiff = 0
let temp_maxdiff = 0
for (const metric of copy) {
for (const other_metric of new_metrics) {
if (metric[0] === other_metric[0]) {
metric.other = other_metric[1]
if (other_metric[1] < metric[1]) {
metric.diff = ((other_metric[1] / metric[1]) - 1) * 100
} else {
metric.diff = ((metric[1] / other_metric[1]) - 1) * -100
}
if (temp_maxdiff == 0 || temp_maxdiff < metric.diff) {
temp_maxdiff = metric.diff
}
if (temp_mindiff == 0 || temp_mindiff > metric.diff) {
temp_mindiff = metric.diff
}
}
}
}
set_maxdiff(temp_maxdiff)
set_mindiff(temp_mindiff)
setCurrent_metrics(copy)
};
reader.readAsText(e.target.files[0]);
}
```
--------------------------------
### Script Engine Flow
Source: https://github.com/intel/perfspect/blob/main/ARCHITECTURE.md
Illustrates the process of defining, generating, and executing collection scripts on targets using a controller script.
```text
1. Scripts defined in code with templates and dependencies
2. Controller script generated from concurrent + sequential scripts
3. Scripts and dependencies copied to target temp directory
4. Controller runs all scripts, captures outputs
5. Outputs parsed and returned to caller
```
--------------------------------
### Trim Metrics by Skipping First 30 Seconds
Source: https://github.com/intel/perfspect/blob/main/docs/perfspect_metrics_trim.md
Use this command to exclude the initial 30 seconds of metric data. Specify the input directory or file path.
```bash
$ perfspect metrics trim --input perfspect_2025-11-28_09-21-56 --start-offset 30
```
--------------------------------
### Set Core Count on Local Host
Source: https://github.com/intel/perfspect/blob/main/docs/perfspect_config.md
Sets the number of physical cores per processor on the local machine. Use caution as invalid configurations may destabilize the system.
```bash
$ perfspect config --cores 32
```
--------------------------------
### Handling Signals in Metrics Command
Source: https://github.com/intel/perfspect/blob/main/docs/signal-handling.md
The handleSignals goroutine listens for signals and context cancellation to trigger a shutdown sequence. It cancels the context and signals child processes.
```Go
go sm.handleSignals()
signal.Notify(sm.sigChannel, syscall.SIGINT, syscall.SIGTERM)
select {
case <-sm.sigChannel:
// Signal received, trigger shutdown
sm.triggerShutdown()
case <-sm.ctx.Done():
// Context cancelled, already shutting down
return
}
```
--------------------------------
### App Component State Management
Source: https://github.com/intel/perfspect/blob/main/cmd/metrics/resources/base.html
Manages the state for the main application component, including selected tabs, link visibility, min/max difference values, and the current set of metrics. It also includes logic to detect highlighted metrics based on thresholds.
```javascript
function App() {
const [systemTabs, setSystemTabs] = React.useState(0);
const [openlink, setOpenlink] = React.useState(true);
const [maxdiff, set_maxdiff] = React.useState(0);
const [mindiff, set_mindiff] = React.useState(0);
const handleChange = (event, newSystemTabs) => {
setSystemTabs(newSystemTabs);
};
const handleCloselink = () => {
setOpenlink(false)
};
const all_metrics = <<.ALLMETRICS>>
const [current_metrics, setCurrent_metrics] = React.useState(JSON.parse(JSON.stringify(all_metrics)));
const [hasHighlightedMetrics, setHasHighlightedMetrics] = React.useState(false);
const description = <<.DESCRIPTION>>
const metadata = <<.METADATA>>
const system_summary = <<.SYSTEMSUMMARY>>
// Check for highlighted metrics whenever current_metrics changes
React.useEffect(() => {
// Look for any metrics that exceed their thresholds
const hasHighlighted = current_metrics.some(row => row[5] === "Yes");
setHasHighlightedMetrics(hasHighlighted);
}, [current_metrics]);
// MetricsTable component
const MetricsTable = ({ data, filterPrefix = null, showComparison = false, containerStyle = {} }) => {
const filteredData = filterPrefix ? data.filter((row) => {
// filterPrefix is either null or an array of strings
return filterPrefix.some(prefix => row[0].startsWith(prefix));
}) : data;
const hasOtherComparison = data.length > 0 && data[0].hasOwnProperty("other");
// If filtering results in no data, show a message
if (filterPrefix && filteredData.length === 0) {
return (
No additional TMA metrics collected.
);
}
// Create the table
return (
{hasHighlightedMetrics && (
{"Metrics with a mean value exceeding their threshold formula are highlighted in yellow, indicating potential performance issues or anomalies that may require further investigation. Hover over the warning icon next to the mean value for more information."}
)}
Metric
Mean
Min
Max
Stddev
{showComparison && hasOtherComparison && Other Mean}
{showComparison && hasOtherComparison && Diff}
{filteredData.map((row) => {
co
```
--------------------------------
### Define a New Table in PerfSpect
Source: https://github.com/intel/perfspect/blob/main/CONTRIBUTING.md
Go code structure for defining a new table in PerfSpect, including its name, script references, and fields.
```go
{
YourTableName: {
Name: YourTableName,
ScriptNames: []string{script.YourScriptName},
FieldsFunc: YourTableValues},
}
func YourTableValues() []table.FieldDefinition {
return []table.FieldDefinition{
// Define fields here
}
}
```
--------------------------------
### Root-Level Signal Handler Logic
Source: https://github.com/intel/perfspect/blob/main/docs/signal-handling.md
This handler is active during the pre-command update check. It logs the received signal, calls a cleanup function, and exits the application.
```Go
SIGINT or SIGTERM received
-> Log the signal
-> Call terminateApplication() to clean up (close log file, remove temp directory)
-> os.Exit(1)
```
--------------------------------
### Target Remote Host with SSH Key
Source: https://github.com/intel/perfspect/blob/main/README.md
Use this command to target a single remote system when you have a pre-configured private key for SSH access. Ensure the remote user has password-less sudo access.
```text
./perfspect report --target 192.168.1.42 --user fred --key ~/.ssh/fredkey
```
--------------------------------
### NUMA Remote DRAM Reads Chart Configuration
Source: https://github.com/intel/perfspect/blob/main/cmd/metrics/resources/base.html
Configures the NUMA chart using the base line chart configuration. Displays the 'Remote DRAM Reads %' metric.
```javascript
let numa = {
...base_line,
series: [
{
name: "Remote DRAM Reads %",
type: 'line',
data: <<.REMOTENUMA>>,
},
],
}
```
--------------------------------
### Set Governor on Remote Targets
Source: https://github.com/intel/perfspect/blob/main/docs/perfspect_config.md
Configures the CPU scaling governor for multiple remote targets specified in a YAML file. Ensure the 'targets.yaml' file is correctly formatted.
```bash
$ perfspect config --gov performance --targets targets.yaml
```