Metrics

Retrieves event metrics by type and date

Let's generate our last command, metrics, which will be useful to monitor the usage of our platform events.

sf events metrics

Let's generate our scaffold by running:

sf dev generate command events:metrics

Here is the code for the metrics command, notice that this time we are using the query method from the Connection object, this is the same query from JSForce, and will allow us to perform SOQL operations. Also, we ware using the this.table utility to display the information on our terminal on a handy table.

import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
import { Messages } from '@salesforce/core';

Messages.importMessagesDirectory(__dirname);
const messages = Messages.load('events-plugin', 'events.metrics', [
  'summary',
  'description',
  'examples',
  'flags.org.summary',
  'flags.type.summary',
  'flags.start-date.summary',
  'flags.end-date.summary',
]);

export type Metric = {
  Name: string;
  Value: number;
  StartDate: string;
  EndDate: string;
};

export type EventsMetricsResult = {
  metrics: Metric[];
};

export default class EventsMetrics extends SfCommand<EventsMetricsResult> {
  public static summary = messages.getMessage('summary');
  public static description = messages.getMessage('description');
  public static examples = messages.getMessages('examples');

  public static flags = {
    'target-org': Flags.requiredOrg({
      char: 'o',
      summary: messages.getMessage('flags.org.summary'),
      required: true,
    }),
    'start-date': Flags.string({
      char: 's',
      summary: messages.getMessage('flags.start-date.summary'),
      dependsOn: ['end-date'],
    }),
    'end-date': Flags.string({
      char: 'e',
      summary: messages.getMessage('flags.end-date.summary'),
      dependsOn: ['start-date'],
    }),
    type: Flags.string({
      char: 't',
      summary: messages.getMessage('flags.type.summary'),
      options: [
        'PLATFORM_EVENTS_PUBLISHED',
        'PLATFORM_EVENTS_DELIVERED',
        'CHANGE_EVENTS_PUBLISHED',
        'CHANGE_EVENTS_DELIVERED',
      ],
    }),
  };

  public async run(): Promise<EventsMetricsResult> {
    const { flags } = await this.parse(EventsMetrics);

    const org = flags['target-org'];
    const type = flags.type;
    const startDate = flags['start-date'];
    const endDate = flags['end-date'];

    // Get connection information
    const conn = org.getConnection();

    // Build SOQL query
    let soql = 'SELECT Name, StartDate, EndDate, Value FROM PlatformEventUsageMetric';

    if (type || startDate || endDate) {
      soql += ' WHERE ';
    }

    if (type) {
      soql += `Name='${type}' `;
    }

    if (startDate && endDate) {
      if (type) soql += ' AND ';
      soql += `StartDate>=${startDate}T00:00:00.000Z AND EndDate<=${endDate}T00:00:00.000Z`;
    }

    // Execute query using JSForce
    const results = await conn.query(soql);

    // Remove the `attributes` field
    const metrics = results.records.map((m) => {
      delete m.attributes;
      return m;
    }) as Metric[];

    // Render metrics on a table
    this.table(
      metrics,
      {
        Name: {},
        Value: {},
        StartDate: {},
        EndDate: {},
      },
      {
        ...flags,
      }
    );

    return {
      metrics,
    };
  }
}

And here is the documentation for the metrics command.

# summary

Retrieves event metrics by type and date

# description

It retrieves event metrics by type and date using SOQL

# flags.type.summary

Metric type

# flags.start-date.summary

Start Date (format: YYYY-MM-DD)

# flags.end-date.summary

End Date (format: YYYY-MM-DD)

# flags.org.summary

Login username or alias for the target org.

# examples

- <%= config.bin %> <%= command.id %> --type PLATFORM_EVENTS_DELIVERED
- <%= config.bin %> <%= command.id %> --start-date 2023-01-11 --end-date 2023-01-20