Take advantage of our **Real User Monitoring (RUM) CLI** to upload **Dart symbols and source maps** for your Flutter applications to the Coralogix RUM service.

## Overview

Flutter applications compile to native code and can run on Android, iOS, and the web. Each target platform requires a different symbol or map file type for Coralogix to translate obfuscated stack traces back to your original source code. Upload each symbol type separately using the appropriate CLI command:

| Symbol type            | File          | Target platform       | CLI command           |
| ---------------------- | ------------- | --------------------- | --------------------- |
| Dart symbols           | `.symbols`    | Android, iOS, desktop | `upload-dart-symbols` |
| dSYM                   | `.dSYM`       | iOS (native crashes)  | `upload-dsym`         |
| ProGuard mapping       | `mapping.txt` | Android               | `upload-proguard`     |
| JavaScript source maps | `.js.map`     | Flutter web           | `upload-source-maps`  |

## Prerequisites

Before sending your data, verify that your S3 bucket has been properly set up and configured. For details on using an S3 bucket for data archiving, refer to the [Coralogix documentation on S3 buckets](https://coralogix.com/docs/user-guides/data-flow/s3-archive/connect-s3-archive/index.md).

## API key

To use this API you need to [create](https://coralogix.com/docs/user-guides/account-management/api-keys/api-keys/index.md) a personal or team API key. It's recommended to use permission presets, as they are automatically updated with all relevant permissions. Alternatively, you can manually add individual permissions.

| Preset        | Action                                                      | Description                                 |
| ------------- | ----------------------------------------------------------- | ------------------------------------------- |
| SourceMapping | `SOURCE-MAPPING:READMAPPING` `SOURCE-MAPPING:UPLOADMAPPING` | Read RUM source maps Upload RUM source maps |

## Install the RUM CLI

1.

Open a terminal or command prompt.

2.

Run the following command to install the CLI globally:

`npm i @coralogix/rum-cli`

3.

Once the installation is complete, you can use the CLI by running the `coralogix-rum-cli` command in your terminal.

## Upload symbols and source maps

Upload each symbol type separately using the matching CLI command.

### Upload Dart symbols

```bash
coralogix-rum-cli upload-dart-symbols -k <privateKey> -a <application> -v <version> -f <folderPath> -e <env> -c <commitHash> -n <repoName> -o <orgName>
```

| Option                            | Description                                                                              |
| --------------------------------- | ---------------------------------------------------------------------------------------- |
| `-k, --private-key <privateKey>`  | Your API key to authenticate with the Coralogix API                                      |
| `-a, --application <application>` | Name of the application                                                                  |
| `-v, --version <version>`         | The application version. Must match the version used by the RUM SDK.                     |
| `-f, --folder-path <folderPath>`  | Path to the `.symbols` file                                                              |
| `-e, --env <env>`                 | The region associated with your Coralogix domain: EU1, EU2, US1, US2, US3, AP1, AP2, AP3 |
| `-c, --commit-hash <commitHash>`  | GitHub commit hash (optional)                                                            |
| `-n, --repo-name <repoName>`      | GitHub repository name (optional)                                                        |
| `-o, --org-name <orgName>`        | GitHub organization name (optional)                                                      |
| `--override`                      | Override existing Dart symbols (optional)                                                |
| `--merge`                         | Merge with existing Dart symbols (optional)                                              |

### Upload dSYM (iOS)

```bash
coralogix-rum-cli upload-dsym -k <privateKey> -a <application> -v <version> -f <folderPath> -e <env> -c <commitHash> -n <repoName> -o <orgName>
```

| Option                            | Description                                                                              |
| --------------------------------- | ---------------------------------------------------------------------------------------- |
| `-k, --private-key <privateKey>`  | Your API key to authenticate with the Coralogix API                                      |
| `-a, --application <application>` | Name of the application                                                                  |
| `-v, --version <version>`         | The application version. Must match the version used by the RUM SDK.                     |
| `-f, --folder-path <folderPath>`  | Path to the `.dSYM` file                                                                 |
| `-e, --env <env>`                 | The region associated with your Coralogix domain: EU1, EU2, US1, US2, US3, AP1, AP2, AP3 |
| `-c, --commit-hash <commitHash>`  | GitHub commit hash (optional)                                                            |
| `-n, --repo-name <repoName>`      | GitHub repository name (optional)                                                        |
| `-o, --org-name <orgName>`        | GitHub organization name (optional)                                                      |

### Upload ProGuard mapping (Android)

```bash
coralogix-rum-cli upload-proguard -k <privateKey> -a <application> -v <version> -f <folderPath> -e <env> -c <commitHash> -n <repoName> -o <orgName>
```

| Option                            | Description                                                                              |
| --------------------------------- | ---------------------------------------------------------------------------------------- |
| `-k, --private-key <privateKey>`  | Your API key to authenticate with the Coralogix API                                      |
| `-a, --application <application>` | Name of the application                                                                  |
| `-v, --version <version>`         | The application version. Must match the version used by the RUM SDK.                     |
| `-f, --folder-path <folderPath>`  | Path to the `mapping.txt` file                                                           |
| `-e, --env <env>`                 | The region associated with your Coralogix domain: EU1, EU2, US1, US2, US3, AP1, AP2, AP3 |
| `-c, --commit-hash <commitHash>`  | GitHub commit hash (optional)                                                            |
| `-n, --repo-name <repoName>`      | GitHub repository name (optional)                                                        |
| `-o, --org-name <orgName>`        | GitHub organization name (optional)                                                      |

### Upload JavaScript source maps (Flutter web)

```bash
coralogix-rum-cli upload-source-maps -k <privateKey> -a <application> -v <version> -f <folderPath> -e <env> -c <commitHash> -n <repoName> -o <orgName>
```

| Option                            | Description                                                                              |
| --------------------------------- | ---------------------------------------------------------------------------------------- |
| `-k, --private-key <privateKey>`  | Your API key to authenticate with the Coralogix API                                      |
| `-a, --application <application>` | Name of the application                                                                  |
| `-v, --version <version>`         | The application version. Must match the version used by the RUM SDK.                     |
| `-f, --folder-path <folderPath>`  | Path to the folder containing the `.js.map` files                                        |
| `-e, --env <env>`                 | The region associated with your Coralogix domain: EU1, EU2, US1, US2, US3, AP1, AP2, AP3 |
| `-c, --commit-hash <commitHash>`  | GitHub commit hash (optional)                                                            |
| `-n, --repo-name <repoName>`      | GitHub repository name (optional)                                                        |
| `-o, --org-name <orgName>`        | GitHub organization name (optional)                                                      |

## Upload symbols using a script

To simplify uploading symbols using the Coralogix RUM CLI, you can create a bash script that automates the task. Follow these steps to set up the script for CI and non-CI integrations.

### CI integration

1.

Create a new file named `upload-flutter-symbols.sh` and open it for editing.

2.

Copy and paste the following script into the file, replacing the placeholder values with your actual information:

```bash
#! /usr/bin/env bash

# Replace these values with your actual information
REPO_NAME="your-repo-name"
ORG_NAME="your-github-username"
APPLICATION="your-application-name"
ENV="your-environment"
PRIVATE_KEY="your-coralogix-private-key"
VERSION="your-application-version"
DART_SYMBOLS_PATH="path/to/app.symbols"
DSYM_PATH="path/to/App.dSYM"
PROGUARD_PATH="path/to/mapping.txt"
JS_MAPS_PATH="path/to/web/source-maps"

# Get the commit hash using git rev-parse
COMMIT_HASH=$(git rev-parse HEAD)

# Upload Dart symbols
coralogix-rum-cli upload-dart-symbols -k "$PRIVATE_KEY" -a "$APPLICATION" -v "$VERSION" -f "$DART_SYMBOLS_PATH" -e "$ENV" -c "$COMMIT_HASH" -n "$REPO_NAME" -o "$ORG_NAME"

# Upload dSYM (iOS only)
coralogix-rum-cli upload-dsym -k "$PRIVATE_KEY" -a "$APPLICATION" -v "$VERSION" -f "$DSYM_PATH" -e "$ENV" -c "$COMMIT_HASH" -n "$REPO_NAME" -o "$ORG_NAME"

# Upload ProGuard mapping (Android only)
coralogix-rum-cli upload-proguard -k "$PRIVATE_KEY" -a "$APPLICATION" -v "$VERSION" -f "$PROGUARD_PATH" -e "$ENV" -c "$COMMIT_HASH" -n "$REPO_NAME" -o "$ORG_NAME"

# Upload JavaScript source maps (Flutter web only)
coralogix-rum-cli upload-source-maps -k "$PRIVATE_KEY" -a "$APPLICATION" -v "$VERSION" -f "$JS_MAPS_PATH" -e "$ENV" -c "$COMMIT_HASH" -n "$REPO_NAME" -o "$ORG_NAME"
```

**Note:** The `$VERSION` must match the version field in your RUM SDK initialization.

### Non-CI integration

1.

Open a terminal window.

2.

Run the appropriate command for each symbol type you need to upload. For example, to upload Dart symbols:

```bash
coralogix-rum-cli upload-dart-symbols -k "$PRIVATE_KEY" -a "$APPLICATION" -v "$VERSION" -f "$DART_SYMBOLS_PATH" -e "$ENV" -c "$COMMIT_HASH" -n "$REPO_NAME" -o "$ORG_NAME"
```

**Note:** The `$VERSION` must match the version field in your RUM SDK initialization.

## Optional GitHub information

Use this GitHub information to add context to your uploaded symbols.

| Option                           | Description                                                                                                                                                   |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-c, --commit-hash <commitHash>` | The GitHub commit hash associated with the symbols. Including this hash helps track issues to a specific commit.                                              |
| `-n, --repo-name <repoName>`     | The GitHub repository where the source code is hosted. Helps correlate symbols with the correct repository.                                                   |
| `-o, --org-name <orgName>`       | Your GitHub organization name. Helps attribute symbols to the appropriate organization. These options are not mandatory and can be omitted if not applicable. |

## Available environments

| Environment | Endpoint                                      | Region                                 |
| ----------- | --------------------------------------------- | -------------------------------------- |
| EU1         | `https://ng-api-grpc.coralogix.com:443`       | eu-west-1, Ireland                     |
| EU2         | `https://ng-api-grpc.eu2.coralogix.com:443`   | eu-north-1, Stockholm                  |
| US1         | `https://ng-api-grpc.coralogix.us:443`        | us-east-2, Ohio                        |
| US2         | `https://ng-api-grpc.cx498.coralogix.com:443` | us-west-2, Oregon                      |
| US3         | `https://ng-api-grpc.us3.coralogix.com:443`   | us-west-2, Oregon                      |
| AP1         | `https://ng-api-grpc.app.coralogix.in:443`    | ap-south-1, Mumbai                     |
| AP2         | `https://ng-api-grpc.coralogixsg.com:443`     | ap-southeast-1, Singapore              |
| AP3         | `https://ng-api-grpc.ap3.coralogix.com:443`   | ap-southeast-3, Asia Pacific (Jakarta) |

## Limitations

- **Dart symbols:** 400MB per file
- **JavaScript source maps (Flutter web):** 100MB per folder

## Additional resources

|                |                                                                                                                            |
| -------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Documentation  | [Coralogix Real User Monitoring](https://coralogix.com/docs/user-guides/rum/getting-started/real-user-monitoring/index.md) |
| External links | [Coralogix RUM CLI Library](https://www.npmjs.com/package/@coralogix/rum-cli)                                              |

## Support

**Need help?**

Our world-class customer success team is available 24/7 to walk you through your setup and answer any questions that may come up.

Feel free to reach out to us **via our in-app chat** or by sending us an email at [support@coralogix.com](mailto:support@coralogix.com).