AGENTS.md@telemetry-reporter ยท diff
git:20260923.310e6a4 to git:20261008.ce94fce
11 added, 5 removed. Audit A to A.
# Telemetry Reporter Agent Guide
This directory contains a standalone .NET 10 implementation of the Azure MCP
`server plugin-telemetry` command. Read [README.md](README.md) for user-facing
build, packaging, and usage documentation. This file defines how coding agents
should modify the project.
## Scope and Structure
- `src/ghcfa-telem/` contains the console application.
- `src/Ghcfa.Telemetry/` contains command parsing, validation, telemetry, and
platform-specific machine information behavior.
- `tests/Ghcfa.Telemetry.Tests/` contains the .NET unit tests.
- `resources/` contains Azure MCP allowlists embedded by `Ghcfa.Telemetry`.
- `eng/scripts/Build-Native.ps1` creates opt-in Native AOT packages for the
- Azure MCP operating system and architecture matrix.
+ Azure MCP operating system and architecture matrix plus musl Linux.
+ - `eng/native-musl/Dockerfile` supplies the same-architecture Alpine toolchain.
+ - `eng/scripts/NativePackaging.psm1` defines supported targets, host mappings,
+ and runtime/symbol archive and checksum validation.
The repository-level `tests/AGENTS.md` does not apply to this directory.
## Compatibility Requirements
- Preserve the Azure MCP command-line contract, JSON response shape, exit
codes, validation behavior, telemetry event names, and telemetry properties.
- The Microsoft-only telemetry exporter policy is an intentional compatibility
divergence. Preserve `AZURE_MCP_COLLECT_TELEMETRY` as the global opt-out, and
do not add user-configurable Application Insights or OTLP sinks.
- Treat `CompatibilityConstants.AzureMcpCommit` as the source revision for the
copied behavior and allowlists.
- When synchronizing with a newer Azure MCP revision, update the compatibility
constants, embedded resources, implementation, tests, README, and third-party
notices as applicable.
- Keep telemetry disabled in build or smoke-test scenarios that invoke the
executable.
- Add XML summary comments to every declared C# type, including test and nested
types.
## Build and Test
Run .NET commands from this directory so `global.json` selects the expected SDK
and Microsoft Testing Platform runner:
```powershell
dotnet build .\ghcfa-telem.slnx --configuration Release
dotnet test .\ghcfa-telem.slnx --configuration Release --no-build
```
Normal builds are framework-dependent. Native AOT is opt-in and supports
- `win-x64`, `win-arm64`, `linux-x64`, `linux-arm64`, `osx-x64`, and
- `osx-arm64`. Follow the host mapping and platform toolchain prerequisites in
- the README. Smoke tests run only when the target RID matches the host RID;
- cross-compiled Windows and macOS ARM64 packages report an explicit skip.
+ `win-x64`, `win-arm64`, `linux-x64`, `linux-arm64`, `linux-musl-x64`,
+ `linux-musl-arm64`, `osx-x64`, and `osx-arm64`. Follow the host mapping and
+ platform toolchain prerequisites in the README. Musl builds run in Alpine
+ containers on matching-architecture glibc Linux hosts. Their smoke tests run
+ in Alpine even though the orchestration host uses glibc. Other executable smoke
+ tests run when the target RID matches the host RID; cross-compiled Windows and
+ macOS ARM64 packages report an explicit skip.
## Versioning
- Nerdbank.GitVersioning is configured by `version.json` with a `0.1`
major/minor version and `pathFilters: ["."]`.
- Do not add hard-coded `<Version>` properties to project files.
- Scripts that need the computed package version must invoke NBGV's
`GetBuildVersion` target and read `NuGetPackageVersion`.
- Keep the NBGV package reference private and centrally versioned through
`Directory.Packages.props`.
## Repository Integration
This project is intentionally independent of the root npm build and existing
CI workflows. Do not modify root build scripts, package manifests, or CI
configuration to include it unless the user explicitly requests that work.