Custom Metrics

sfp provides multiple ways to enhance your metrics with custom data:

1. Report custom metrics using the metrics:report command

2. Add organization-wide custom tags to all metrics (sfp-pro only)

sfp metrics report

Report a custom metric to any sfp supported metric provider

USAGE
  $ @flxbl-io/sfp metrics report -m <value> -t gauge|counter|timer [-v <value>] [-g <value>] [--loglevel
    trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]

FLAGS
  -g, --tags=<value>       tags for metric
  -m, --metric=<value>     (required) metrics to publish
  -t, --type=<option>      (required) type of metric
                           <options: gauge|counter|timer>
  -v, --value=<value>      value of metric
      --loglevel=<option>  [default: info] logging level for this command invocation
                           <options: trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL>

DESCRIPTION
  Report a custom metric to any sfp supported metric provider

EXAMPLES
  $ sfp metrics:report -m <metric> -t <type> -v <value>

Custom Tags Configuration

	sfp-pro	sfp (community)
Availability	✅	❌
From	August 25

sfp-pro allows you to configure custom tags that will be automatically added to ALL metrics sent by sfp. This is useful for adding consistent organizational metadata without modifying individual commands.

Setting Custom Tags

Use the sfp config set command with the custom-tag.* prefix:

# Set a team tag
sfp config set custom-tag.team platform-engineering

# Set an environment tag
sfp config set custom-tag.environment production

# Set a repository tag
sfp config set custom-tag.repository myorg/myrepo

# Set any custom tag
sfp config set custom-tag.<tagname> <value>

Viewing Custom Tags

To see all configured custom tags:

# List all config including custom tags
sfp config list

# Filter for custom tags only
sfp config list | grep custom-tag

Removing Custom Tags

# Unset a specific tag
sfp config unset custom-tag.team

# Unset all custom tags (Unix/Linux/Mac)
sfp config list | grep custom-tag | cut -d'=' -f1 | xargs -I {} sfp config unset {}

Scope of Custom Tags

Custom tags follow the standard sfp configuration hierarchy:

• Global tags: Set without --scope local, applies to all projects

• Project-specific tags: Set with --scope local, applies only to current project

• Project tags override global tags when both are present

# Set a global tag
sfp config set custom-tag.organization acme-corp

# Set a project-specific tag
sfp config set custom-tag.project frontend --scope local

How Custom Tags Work

1. Automatic Inclusion: Custom tags are automatically added to every metric sent by sfp

2. Tag Precedence: Command-specific tags override custom tags if there's a conflict

3. GitHub Integration: Repository tags are automatically added when running in GitHub Actions

4. Backend Support: Works with all supported metrics backends (StatsD, DataDog, NewRelic, Splunk)

Example Workflow

# Configure organizational tags
sfp config set custom-tag.team devops
sfp config set custom-tag.environment staging
sfp config set custom-tag.cost-center engineering

# Run any sfp command - tags are automatically included
sfp build --branch main
# Metrics sent: sfpowerscripts.build.scheduled
# Tags: team=devops, environment=staging, cost-center=engineering, branch=main

sfp release --environment uat
# Metrics sent: sfpowerscripts.release.scheduled
# Tags: team=devops, environment=staging, cost-center=engineering, env=uat

Use Cases

Team Attribution

Track metrics by team for resource allocation and performance monitoring:

sfp config set custom-tag.team platform-team
sfp config set custom-tag.squad alpha

Multi-Environment Tracking

Differentiate metrics across environments:

# In CI/CD pipeline for staging
sfp config set custom-tag.environment staging
sfp config set custom-tag.region us-west-2

# In CI/CD pipeline for production
sfp config set custom-tag.environment production
sfp config set custom-tag.region us-east-1

Cost Center Tracking

Associate metrics with cost centers for chargeback:

sfp config set custom-tag.cost-center CC-12345
sfp config set custom-tag.business-unit retail

Project Metadata

Add project-specific context:

sfp config set custom-tag.project customer-portal --scope local
sfp config set custom-tag.version v2.3.0 --scope local
sfp config set custom-tag.release-cycle Q1-2024 --scope local

Best Practices

1. Establish Naming Conventions: Define standard tag names across your organization

2. Use Hierarchical Tags: Organize tags logically (e.g., team, squad, project)

3. Automate Tag Configuration: Set tags in CI/CD pipeline initialization

4. Document Required Tags: Maintain a list of required tags for your organization

5. Regular Audits: Periodically review and clean up unused tags

CI/CD Integration

Configure custom tags in your CI/CD pipeline:

GitHub Actions

- name: Configure Custom Tags
  run: |
    sfp config set custom-tag.team ${{ vars.TEAM_NAME }}
    sfp config set custom-tag.environment ${{ github.ref_name }}
    sfp config set custom-tag.pipeline github-actions
    sfp config set custom-tag.run-id ${{ github.run_id }}

Jenkins

stage('Configure Metrics') {
    steps {
        sh """
            sfp config set custom-tag.team ${env.TEAM_NAME}
            sfp config set custom-tag.environment ${env.BRANCH_NAME}
            sfp config set custom-tag.pipeline jenkins
            sfp config set custom-tag.build-number ${env.BUILD_NUMBER}
        """
    }
}

Azure DevOps

- script: |
    sfp config set custom-tag.team $(TeamName)
    sfp config set custom-tag.environment $(Build.SourceBranchName)
    sfp config set custom-tag.pipeline azure-devops
    sfp config set custom-tag.build-id $(Build.BuildId)
  displayName: 'Configure Custom Tags'

Limitations

• Custom tags are loaded once at command initialization

• Tag values must be strings

• Tag names should follow your metrics backend's naming conventions

• Maximum number of tags depends on your metrics backend limitations

Note: Custom tags are only available in sfp-pro edition. Community edition users must add tags manually to each command or upgrade to sfp-pro.