Add --record option to crank-agent for custom measurements

[Copilot]

Summary

This PR implements the --record (or -r) command line option for crank-agent to enable recording custom measurements that are automatically added to every benchmark job the agent runs.

Motivation

Agents often need to record system-specific information like OpenSSL version, kernel version, or environment configuration for every benchmark. Previously, there was no way to automatically capture this information without modifying each benchmark. This feature allows administrators to configure custom measurements once at agent startup, which then apply to all benchmarks.

Usage

The new option accepts name=value pairs and can be specified multiple times. Command substitution is handled by the shell before the arguments reach the agent:

# Simple values
crank-agent --record "environment=production" --record "region=us-west"

# Command substitution on Linux/macOS (shell expands before agent receives)
crank-agent --record "system/openssl=$(openssl version)" \
            --record "system/kernel=$(uname -r)" \
            --record "system/hostname=$(hostname)"

# Command substitution on Windows PowerShell
crank-agent --record "system/dotnet=$(dotnet --version)" `
            --record "system/os=$(systeminfo | Select-String 'OS Name')"

# Short form
crank-agent -r "test=value" -r "other=$(date)"

Implementation Details

Format:

• Name and value are separated by the first = character
• Names must be non-empty
• Values can be empty strings

Command Substitution:

• Handled by the shell before arguments reach the agent
• The agent receives the already-expanded values
• No command execution is performed by the agent itself

Automatic Addition:

• Custom measurements are added to job.Measurements when each job starts
• Metadata is automatically created with sensible defaults (Operation.First for Aggregate/Reduce)
• Duplicate metadata is prevented

Error Handling:

• Invalid formats (missing =, empty name): logged as warnings and skipped
• All errors are non-fatal to agent startup

Example Output

When a job runs on an agent started with --record "system/openssl=$(openssl version)", the results will include:

Measurement:

{
  "name": "system/openssl",
  "timestamp": "2024-02-23T13:01:56.12Z",
  "value": "OpenSSL 3.0.13 30 Jan 2024"
}

Metadata:

{
  "source": "Agent",
  "name": "system/openssl",
  "aggregate": "First",
  "reduce": "First",
  "format": "",
  "longDescription": "Custom measurement: system/openssl",
  "shortDescription": "system/openssl"
}

Changes

• Added _recordOption command line option with -r|--record flags
• Added _customMeasurements dictionary to store parsed measurements
• Enhanced MarkAsRunning() to add custom measurements and metadata to each job
• Added comprehensive documentation in docs/measurements.md

Security Considerations

The agent reads values directly from command line arguments provided by the administrator. Command substitution is handled by the shell, not by the agent, following standard Unix conventions. The database should not record sensitive information per the issue requirements.

Fixes dotnet/crank#847

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Record specific measurements from the agent</issue_title> <issue_description>The agent application should accept a custom command line argument to define custom measurements. For instance we could record the openssl version, or the kernel version, ...

We shouldn't be concerned about sensitive information since the db should not record these. Hence we can just pass the values to the command line even if they come from ENV.

A possible usage would be:

crank-agent --record "system/openssl=$(openssl version -v)"

• The name and value are separated by the first = char.
• Switches could be -r|--record.
• For each benchmark that this agent runs the value would be added automatically.
• The argument usage should be repeatable. </issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes dotnet/crank#847

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.