perf-ecosystem.yml

import { Aside } from ‘@astrojs/starlight/components’;

perf-ecosystem.yml is a single configuration file that all ecosystem tools discover automatically. Place it in your project root and each tool connects itself to the configured services.

Discovery

Tools walk up the directory tree from the current working directory until they find perf-ecosystem.yml or reach the .git boundary. No environment variable or flag is needed — discovery is automatic.

Full Reference

# Schema version: 1.0

version: "1.0"

workspace:
  name: "my-application"       # Default project name in perf-results-db
  team: "platform-team"
  environment: staging         # dev | staging | prod

services:
  perf_results_db:
    url: "http://localhost:4000"
    api_key: "${PERF_RESULTS_DB_API_KEY}"
    project_id: "${PERF_RESULTS_DB_PROJECT_ID}"   # UUID from perf-results-db dashboard

  perf_monitor:
    url: "https://monitor.example.com"
    api_key: "${PERF_MONITOR_API_KEY}"

  dummydatagenpro:
    url: "https://dummydatagenpro.co.uk"
    api_key: "${DUMMYDATA_API_KEY}"

  perf_lint_api:
    url: "https://perflint.martkos-it.co.uk"
    api_key: "${PERF_LINT_API_KEY}"

  perf_advisor:
    url: "http://localhost:7071"
    api_key: "${PERF_ADVISOR_API_KEY}"

licenses:
  perf_reporting: "${PERF_REPORTING_LICENSE}"
  perf_lab: "${PERF_LAB_LICENSE}"
  perf_autocorrelator_pro: "${PERF_AUTOCORRELATOR_LICENSE}"
  perf_migrator: "${PERF_MIGRATOR_LICENSE}"
  suite_key: "${MARTKOS_SUITE_KEY}"  # Martkos Suite: single key unlocks all products

tools:
  default: jmeter              # jmeter | k6 | gatling
  jmeter:
    home: "/opt/apache-jmeter-5.6.3"
    image: "ghcr.io/markslilley/perf-jmeter:latest"
  k6:
    image: "ghcr.io/markslilley/perf-k6:latest"
  gatling:
    image: "ghcr.io/markslilley/perf-gatling:latest"

thresholds:
  response_time:
    avg_max_ms: 500
    p95_max_ms: 1500
    p99_max_ms: 3000
  error_rate:
    max_percent: 1.0
  apdex:
    min_score: 0.85

notifications:
  slack:
    webhook_url: "${SLACK_WEBHOOK_URL}"
    channel: "#perf-alerts"
    on_failure: true
    on_sla_breach: true
    on_regression: true

integrations:
  push_to_results_db: true     # Auto-push metrics after test runs / reports
  auto_lint_on_run: false       # Run perf-lint before executing scripts
  advisor_on_complete: false    # Run perf-advisor AI analysis after reports
  migrator_validate: false      # Auto-run perf-lint on perf-migrator output
  compare_on_upload: false      # Auto-run statistical regression check on upload

Environment Variable Interpolation

Values matching ${VAR_NAME} are substituted before parsing. An unresolved variable resolves to null — the integration is silently disabled rather than throwing an error. This means a partial config (e.g., only perf_results_db configured) works correctly without needing to remove unconfigured sections.

services:
  perf_results_db:
    api_key: "${PERF_RESULTS_DB_API_KEY}"   # → null if var not set → DB integration disabled

Store secrets in .env (excluded from git) or your CI/CD secrets store. Never commit API keys directly.

Minimal Config

You don’t need all sections. A minimal setup connecting only perf-results-db:

version: "1.0"

services:
  perf_results_db:
    url: "http://localhost:4000"
    api_key: "${PERF_RESULTS_DB_API_KEY}"
    project_id: "${PERF_RESULTS_DB_PROJECT_ID}"

integrations:
  push_to_results_db: true

Which Tools Consume Which Sections

Section	Consumed By
`services.perf_results_db`	perf-compare, perf-monitor, perf-reporting
`services.perf_lint_api`	perf-lint (remote rule sync), perf-migrator (post-convert lint)
`services.dummydatagenpro`	Future: perf-ci-pipelines data generation step
`licenses.*`	perf-reporting, perf-lab, perf-autocorrelator-pro, perf-migrator
`tools.*`	perf-ci-pipelines, perf-monitor (executor image selection)
`thresholds.*`	perf-reporting (SLA checks), perf-compare (simple threshold), perf-monitor (alert thresholds)
`notifications.*`	perf-monitor (alert routing)
`integrations.*`	All tools — control auto-integration behaviour

Getting the Example File

curl -O https://raw.githubusercontent.com/markslilley/perf-ecosystem/main/perf-ecosystem.example.yml
cp perf-ecosystem.example.yml perf-ecosystem.yml