Backfill AWS Account Alias

The AWS Observability Solution uses an account field on collector sources to identify AWS accounts in dashboards and the AWS Observability hierarchy. By default, this field contains the 12-digit AWS account ID. If you want to replace numeric account IDs with human-readable aliases (for example, prod, dev, or billing) on sources that were created before you configured an alias, use the backfill script.

When to use this script

Use this script when:

• You deployed the AWS Observability Solution without setting an account alias and now want to add one.
• You changed your account alias after initial deployment and need to update existing sources to reflect the new alias.
• You have multiple AWS accounts and want to apply distinct aliases to each account's sources for easier identification in dashboards.

note

This script only updates existing sources. New sources created by subsequent CloudFormation or Terraform deployments will use the alias configured in the deployment parameters.

How it works

The script operates in two steps:

Step 1: Prepare

The script scans your Sumo Logic org for collectors matching the aws-observability-<account-id> naming pattern (where <account-id> is the 12-digit AWS account ID), fetches all sources under those collectors, and generates a CSV file for review. Each row in the CSV represents a source where the accountid or account field matches the 12-digit AWS account ID extracted from the collector name.

If a source already has a different value in its account field (indicating a previously configured alias), the script pre-fills that value in the alias column.

Step 2: Apply

After you review and edit the CSV, the script reads it back and updates the account field on each source where you have set override_account_field_with_alias to Yes. The update uses optimistic locking (ETags) to prevent conflicts.

Prerequisites

• Python 3.13 or later
• requests library — Install with:

  pip install requests

• Sumo Logic Access Key — An access ID and access key with permissions to read and modify collectors and sources. See Access Keys for more information.
• Deployment environment identifier — The Sumo Logic deployment where your account resides (for example, au, ca, ch, de, eu, fed, jp, kr, us1, or us2).

Input parameters

Parameter	Required	Description
--access-id	Yes	Your Sumo Logic Access ID.
--deploy-env	Yes	The Sumo Logic deployment environment (for example, au, ca, ch, de, eu, fed, jp, kr, us1, or us2).
--filename	Step 2 only	Path to the edited CSV file to apply.
--dry-run	Step 2 only	Validate and show what would be updated without making API calls.
--log-dir	No	Directory for the log file. Created if it does not exist. Defaults to the current directory.

Run the script

Step 1: Generate the CSV

Run the script without the --filename parameter to generate a CSV file listing all sources eligible for alias backfill. The script prompts for your access key interactively:

python backfill_aws_account_alias.py \
  --access-id <SUMO_ACCESS_ID> \
  --deploy-env <DEPLOYMENT>

This creates a file named backfill_aws_account_alias.csv in the current directory.

CI/automation

For automation or CI pipelines, set the SUMO_ACCESS_KEY environment variable instead of using the interactive prompt.

Review and edit the CSV

Open the generated CSV file. Each row contains the following columns:

Column	Description
collector_id	The Sumo Logic collector ID. Do not modify.
collector_name	The collector name. Do not modify.
source_id	The source ID. Do not modify.
source_name	The source name. Do not modify.
accountid	The 12-digit AWS account ID extracted from the collector name. Do not modify.
alias	The alias to set on the account field. Fill in your desired alias.
override_account_field_with_alias	Set to Yes to apply the alias, or leave as No to skip.

For each source you want to update:

1. Enter a value in the alias column.
2. Change override_account_field_with_alias to Yes.

Alias naming rules

The alias must follow AWS account alias naming conventions:

• 3 to 63 characters in length.
• Contains only lowercase letters, digits, and hyphens.
• Does not start or end with a hyphen.
• Does not contain consecutive hyphens (--).

Step 2: Apply the changes

Before applying, you can preview what would change without making any API calls:

python backfill_aws_account_alias.py \
  --access-id <SUMO_ACCESS_ID> \
  --deploy-env <DEPLOYMENT> \
  --filename backfill_aws_account_alias.csv \
  --dry-run

When you are ready, run the script with the --filename parameter pointing to your edited CSV:

python backfill_aws_account_alias.py \
  --access-id <SUMO_ACCESS_ID> \
  --deploy-env <DEPLOYMENT> \
  --filename backfill_aws_account_alias.csv

The script validates each alias, skips invalid entries with a warning, and updates the account field on all valid sources marked with override_account_field_with_alias=Yes.

Error handling

The script handles the following scenarios:

Scenario	Behavior
Transient API errors (429, 500, 502, 503, 504)	Retries up to 3 times with exponential backoff.
Invalid alias format	Skips the row and prints a warning with the validation error.
Missing collector_id or source_id	Skips the row and prints an error.
Source fetch failure	Skips the row and prints the HTTP status code.
Concurrent modification conflict	Uses ETag-based optimistic locking to detect conflicts.

Example workflow

1. Generate the CSV:

   python backfill_aws_account_alias.py \
     --access-id suXXXXXX \
     --deploy-env us2

2. Open backfill_aws_account_alias.csv in a spreadsheet editor.
3. For account 123456789012, enter prod in the alias column and set override_account_field_with_alias to Yes.
4. Preview the changes:

   python backfill_aws_account_alias.py \
     --access-id suXXXXXX \
     --deploy-env us2 \
     --filename backfill_aws_account_alias.csv \
     --dry-run

5. Apply changes:

   python backfill_aws_account_alias.py \
     --access-id suXXXXXX \
     --deploy-env us2 \
     --filename backfill_aws_account_alias.csv

6. Verify the updated alias appears in your AWS Observability hierarchy.