Skip to main content

Guides

Set the API token​

The audit log API token is a static token configured to grant your caller service access to the API endpoint.

  1. As an admin user, go to "App Settings" in the left-hand menu under "Admin."
  2. Navigate down to the "External access" section.
  3. Open the entry titled audit-log-api-access, which is a static token that has been pre-created for you with the recommended settings.

Tip: By default, we use access restrictions to restrict the token's scope to the audit-log plugin and audit.log.read permission. Tokens with different plugin or permission scope will cause API requests to respond with 403 Forbidden.

  1. In the "Token" section, paste in a secure API token value of your choice for API authentication. Keep this value in a safe place as you won't be able to see it in Portal.

Tip: The token must be at least 8 characters long and not contain spaces. With node, you can generate a token in the Terminal via the command: node -p 'require("crypto").randomBytes(24).toString("base64")'

  1. Click "Update item" in the bottom right corner.
  2. Click "Save" in the bottom right corner and wait for Portal to reload with the new configuration.

Exclude certain events or actors from logs​

In Portal’s App Settings, you can configure which combinations of actor and event you want to exclude from being saved to the audit trail. By default, entity-fetch and entity-facets events from all plugin actors are excluded because they are high-volume, low-value read operations. The same events from synthetic test users are also excluded to prevent noise.

Important: Exclusion rules prevent events from being saved to the audit log database entirely. They will still appear in console logs (if the severity level is configured to log), but will not be queryable via the API.

  1. As an admin user, go to "Plugins" in the left-hand menu under "Admin."
  2. Find the “Audit Log” plugin card in the list and open it.
  3. Add or edit exclusion rules in the UI using the configuration format shown in examples below.
  4. Save your changes.

Example Use Cases​

excludeRules:
 # Exclude high-volume read operations from all plugins
 - actorId: 'plugin:*'
   eventId: 'entity-fetch'

 # Exclude health check events from monitoring services
 - actorId: 'user:default/healthcheck-service'
   eventId: 'entity-validate'

 # Exclude specific scaffolder dry-run tasks
 - actorId: 'plugin:scaffolder'
   eventId: 'task'
   # Note: This excludes ALL task events. Consider filtering by actionType instead.

Wildcard Patterns​

Use wildcards (*) in actorId to exclude patterns of events:

  • plugin:* - Matches all plugin actors
  • plugin:search - Matches only the search plugin
  • user:*/* - Matches any user in any namespace
  • user:default/* - Matches any user in the default namespace

Add audit events to custom plugins​

Save events taking place in your own custom plugins by integrating the Backstage auditor service.

Integrate auditor service​

Declare the auditor service as a plugin dependency:

import {
  coreServices,
  createBackendPlugin,
} from '@backstage/backend-plugin-api';

export const myPlugin = createBackendPlugin({
  pluginId: 'my-plugin',
  register(env) {
    env.registerInit({
      deps: {
        auditor: coreServices.auditor,
        httpRouter: coreServices.httpRouter,
        // ... other dependencies
      },
      async init({ auditor, httpRouter }) {
        // Use the auditor service here
      },
    });
  },
});

Add audit events​

Use the createEvent method to generate audit events. For more on how to use the auditor service, see the Auditor Service Backstage documentation (specifically Naming conventions) and the AuditorService source code.

// Basic usage
const event = await auditor.createEvent({
  eventId: 'entity.created',
  severityLevel: 'high', // 'low' | 'medium' | 'high' | 'critical'
  request: req, // Optional: Express request object
  meta: {
    actionType: 'create',
    queryType: 'mutation',
    entityRef: 'component:default/my-service',
    customField: 'custom-value',
  },
});

// Mark as successful (remove 'await' for non-blocking save)
await event.success();

// OR mark as failed with error details
await event.fail({
  error: new Error('Operation failed'),
  meta: { additionalContext: 'value' },
});

Automatic field extraction​

The PortalAuditorService automatically extracts the following information:

  • Actor ID & Type: From request credentials (user or service principal)
  • Request Method & URL: From the Express request object
  • Plugin ID: From the plugin metadata
  • Event Time: Current timestamp

Special meta fields​

The following fields in the meta object are promoted to dedicated database columns to be queried by the API easily. These fields are removed from the meta JSON blob to avoid duplication.

  • actionType
  • queryType
  • entityRef