[RUM-6573] add optional build_id parameter for Android mapping uploads

[kyletaylored]

When --build-id is provided for Android mapping files, service name, version, and variant are no longer required. This aligns with the native Android gradle task behavior where build_id overrides other metadata fields.

Relates to #1477

What and why?

Adds an optional --build-id parameter to the flutter-symbols upload command for Android mapping files. When provided, build_id overrides the requirement for --service-name, --version, and --flavor, aligning the Flutter CLI behavior with the native Android Gradle task where build_id is the primary identifier.

How?

• Added --build-id CLI option to FlutterSymbolsUploadCommand
• Updated MappingMetadata interface to include optional build_id field and made service, version, and variant optional
• Modified getMappingMetadata() to conditionally include build_id OR service/version/variant based on whether build_id is provided
• Updated parameter validation in verifyParameters() to skip service name and version requirements when --build-id is provided with Android mapping
• Added three test cases covering the new functionality
• Updated README documentation with the new parameter

Review checklist

• Feature or bugfix MUST have appropriate tests (unit, integration)

[fuzzybinary]

@kyletaylored We should touch base on this, since Flutter doesn't actually support build_id (yet) it's weird to add it to the flutter-symbols command.

Instead, we may just want to take the step suggested in #1477 and add a manual android symbols upload command, then have flutter-symbols (and unity-symbols maybe?) call it.

Let me know what you think.

[kyletaylored]

Heya! So what I learned tracking this down is that even though it's for the flutter-symbols command, this is only relevant for the --android-mapping flag. Basically it looks like this:

1. datadog-ci selects the upload function based on CLI flags

   • --ios-mapping-location → DsymUpload
   • --android-mapping-location → AndroidMappingUpload
   • --dart-symbols-location → DartSymbolsUpload
   • --web-sourcemaps-location → SourceMapUpload
     Ref: flutter-symbols/upload.ts#L176-L188

2. Example: Android mapping path

   • --android-mapping-location calls performAndroidMappingUpload(...) and passes VALUE_NAME_JVM_MAPPING (the label used for the JVM mapping “interface” path).
     Refs:

• flutter-symbols/upload.ts#L347
• flutter-symbols/interfaces.ts#L1

3. All symbol types build a common request payload and POST to the same intake endpoint

   • The request builder constructs the multipart payload including:

     • metadata attributes
     • the interface key (e.g., jvm_mapping_file)
     • the file payload

   • Upload goes to the shared endpoint: POST /api/v2/srcmap
     Ref: flutter-symbols/helpers.ts#L7-L16

4. Backend routing + processing is driven by the interface key

   • After upload, symbols hit sourcemap-intake, then flow into sourcemap-processing.
   • sourcemap-processing dispatches based on the interface key (e.g., jvm_mapping_file), which selects the JVM mapping processor/interface implementation and stores results accordingly.
     Ref: internal/sourcemap/jvm_mapping.go

---

So really all this PR does is if the Flutter build is generating an Android app, we can push that build_id with the mapping file – and as a byproduct, we can attach a build ID when uploading any Android mapping file if we're using this as a manual workaround.

And it looks like there was a closed issue in the dart-lang repo (dart-lang/sdk#51941) about dynamic build_ids for iOS and Android, but still working on support for web (dart-lang/sdk#53027).

[evazorro]

Approving the README update on behalf of the Docs team!