Pinpoint Developer Documentation

This developer guide details how to run, execute, query, and debug Go-native Pairwise Jobs (Skia's TryJob equivalent) programmatically and locally.

1. Run a Local Temporal Dev Server

Temporal orchestrates Pinpoint's build, Swarming, and statistical workflows.

Step 1. Install & Start Temporal

If Temporal CLI is not installed, run the official installer script on your terminal:

curl -sSf https://temporal.download/cli.sh | sh

Ensure Temporal is in your PATH: echo export PATH="\$PATH:\$HOME/.temporalio/bin" >> ~/.bashrc.

Launch the local Temporal dev server:

temporal server start-dev

(Optionally pass --db-filename=temporal-db.db if you need persistent workflow runs).

• Temporal Server Port: localhost:7233
• Temporal Web UI: Accessible at http://localhost:8233.

Step 2. Create the perf-internal Namespace

By default, the Go service runs within the perf-internal namespace. You must register it before scheduling workflows:

temporal operator namespace create perf-internal

2. Run the Local Go Pinpoint Service Server

To serve the REST HTTP JSON gateways, start the Pinpoint backend server locally on port 8080:

bazelisk run //pinpoint/go/frontend/cmd:cmd -- --port=:8080

• Local REST API Endpoint: http://localhost:8080

3. Run a Local Temporal Worker

The worker polls the server for queued tasks and executes the actual benchmark workflows.

Start the worker pointing to the shared perf.perf-chrome-public.bisect task queue:

bazelisk run //pinpoint/go/workflows/worker -- \
  --taskQueue=perf.perf-chrome-public.bisect \
  --namespace=perf-internal \
  --local

(The --local flag enables local/development fail-fast bypass of GCP Spanner writes to facilitate smooth local testing).

4. Trigger a Pairwise A/B Job Natively

Approach A: Via cURL REST HTTP API

Make a POST request directly to the local Go Pinpoint API endpoint:

curl -i -X POST "http://localhost:8080/pinpoint/v1/pairwise" \
  -H "Content-Type: application/json" \
  -d '{
    "start_commit": {
      "main": {
        "repository": "https://chromium.googlesource.com/chromium/src.git",
        "git_hash": "b2d27b144e4e4c5661bafc08f7b8494797f6ee1a"
      }
    },
    "end_commit": {
      "main": {
        "repository": "https://chromium.googlesource.com/chromium/src.git",
        "git_hash": "95b3180e9724995eb6d5a85ac3c93140e4506f7e"
      }
    },
    "bot_name": "win-11-perf",
    "benchmark": "speedometer3",
    "story": "Speedometer3",
    "initial_attempt_count": "30",
    "improvement_dir": "Unknown",
    "user_email": "your_email@google.com",
    "job_name": "Programmatic Local Pairwise Run"
  }'

Successfully returns a JSON payload containing your "jobId" (the Temporal Workflow UUID).

Approach B: Via Bazel CLI Sample Utility

Alternatively, you can bypass HTTP APIs entirely and trigger workflows directly using the Go sample tool:

bazelisk run //pinpoint/go/workflows/sample -- \
  --taskQueue=perf.perf-chrome-public.bisect \
  --namespace=perf-internal \
  --pairwise \
  --configuration=win-11-perf \
  --benchmark=speedometer3 \
  --story=Speedometer3 \
  --start-git-hash=b2d27b144e4e4c5661bafc08f7b8494797f6ee1a \
  --end-git-hash=95b3180e9724995eb6d5a85ac3c93140e4506f7e

Approach C: Mimicking a Legacy Pinpoint Job (Recommended for Local Testing)

You can fetch an existing legacy Pinpoint job from production (e.g., from the Chromeperf dashboard), parse its exact configuration, and trigger an identical localized workflow on your local Temporal instance with a single command:

bazelisk run //pinpoint/go/workflows/sample -- \
  --taskQueue=perf.perf-chrome-public.bisect \
  --namespace=perf-internal \
  --mimic-legacy-job=[legacy-job-id]

How it works:

1. Connects securely using your corporate Google login tokens.
2. Fetches and parses the legacy job JSON description from Chromeperf's API (https://pinpoint-dot-chromeperf.appspot.com/api/job/[legacy-job-id]).
3. Decodes the comparison mode and dynamically schedules:
   • Pairwise A/B TryJob (workflows.PairwiseWorkflow) if the legacy job is a try job.
   • Chromeperf Bisection (catapult.CatapultBisectWorkflow) if the legacy job is a performance bisection.
4. Automatically extracts and translates Gerrit patch URLs from pin or tags into native GerritChange protobuf messages on your local treatment commit.

5. Query Job Status & View Results

Once triggered, you can monitor progress and fetch results using three methods:

A. Via Temporal Web UI (Visual Logs)

Open your local browser and navigate to: http://localhost:8233. Note: If the server is running on a remote Cloudtop VM, you may need to access this through Chrome Remote Desktop (go/crd) or set up port forwarding.

• Select the perf-internal namespace from the top-left dropdown.
• Click on your workflow [jobId] to view the real-time execution graph, pending build or Swarming tasks, and full payloads.

B. Via Temporal CLI (Command Line)

Fetch the active workflow progress and state details natively in your terminal:

temporal workflow show \
  -w [your-job-id] \
  -n perf-internal

C. Via Go Pinpoint REST Query API

Once the bisection workflow completes, retrieve the statistical results programmatically:

curl -i -X GET "http://localhost:8080/pinpoint/v1/query?job_id=[your-job-id]"

D. Via Go Pinpoint REST QueryPairwise API (New)

Once a Pairwise/Try Job completes, retrieve the Wilcoxon Signed-Rank test statistical results, control/treatment medians, p-values, and all swarming task IDs:

curl -i -X GET "http://localhost:8080/pinpoint/v1/query-pairwise?job_id=[your-job-id]"