Report Apiview Metrics

Report APIView Metrics

When to Use

• Monitoring progress toward 100% versioned revisions across languages
• Checking cross-language metadata compliance (CrossLanguagePackageId)
• Generating trend charts for APIView platform health
• Reviewing parser compliance over time

What It Produces

A combined report with two metric buckets:

| Bucket | What it measures |

|--------|-----------------|

| versions | % of revisions with a valid PackageVersion, broken out by language and revision type (Automatic, Manual, PullRequest) |

| compliance | % of reviews whose latest revision includes CrossLanguagePackageId (from CrossLanguageMetadata) |

Output is JSON with top-level "versions" and "compliance" keys. With --summary, human-readable tables are printed to stderr.

Defaults

Unless the user says otherwise, always apply these defaults:

• Environment: production
• Months: 6
• Languages: Python, C#, Java, JavaScript, Go (all included by default — do not pass --languages unless user restricts)
• Chart: Include --chart unless user says no charts

Running the Command

Step 1: Run the Command

Show the resolved command and run it immediately in a foreground terminal with a 120-second timeout (timeout: 120000). Clean up stale output first.

New-Item -ItemType Directory -Path output -Force | Out-Null; New-Item -ItemType Directory -Path output/charts -Force | Out-Null; if (Test-Path output/apiview_metrics_output.json) { Remove-Item output/apiview_metrics_output.json }; python cli.py report apiview-metrics --chart --summary 2>$null | Out-File -Encoding UTF8 output/apiview_metrics_output.json

After the command completes, read the output file with read_file to get the JSON results. Then use view_image to display charts at:

• output/charts/apiview_version_trends.png
• output/charts/cross_language_compliance.png

Examples

# Default: 6 months, all languages, production, with charts
python cli.py report apiview-metrics --chart

# With human-readable summary tables on stderr
python cli.py report apiview-metrics --chart --summary

# Custom lookback
python cli.py report apiview-metrics --months 3 --chart

# Specific end date
python cli.py report apiview-metrics --months 6 --end-date 2026-04-30 --chart

# Specific languages only
python cli.py report apiview-metrics --languages Python Java --chart

# Staging environment
python cli.py report apiview-metrics --chart --environment staging

Step 2: Present Results

After reading the output file:

• Summarize the version-coverage trends (highlight languages below 100%)
• Summarize the compliance trends (highlight languages below 100%)
• Show the chart images with view_image

Step 3: Answer Follow-up Questions

For follow-up questions about the same data, read the output file instead of re-running the command.

Available Flags

| Flag | Type | Default | Description |

|------|------|---------|-------------|

| --months | int | 6 | Number of calendar months to look back from end date |

| --end-date / -e | string | today | Inclusive query end date (YYYY-MM-DD) |

| --languages | list | all 5 | Space-separated language names to include |

| --chart | flag | off | Generate PNG trend charts to output/charts/ |

| --summary | flag | off | Print human-readable summary tables to stderr |

| --environment | string | production | production or staging |

Gotchas

• Redirect stdout to a file: Always pipe through | Out-File -Encoding UTF8 output/apiview_metrics_output.json. Do NOT use > which produces UTF-16 in PowerShell 5.1.
• Do NOT use 2>&1: This merges stderr log lines into the JSON output, producing invalid JSON.
• Clean up before running: Delete previous output files before running to avoid presenting stale results.
• Use python cli.py not .\avc: Ensures the correct Python environment is used.
• Use read_file and view_image: Do NOT use additional terminal commands to read output files or display charts.
• Built-in exclusions: c, c++, typespec, swagger, xml are always excluded automatically.