Skip to main content

Audit Logging - Temporal Cloud feature guide

Audit Logging is a feature of Temporal Cloud that provides forensic access information for a variety of operations in the Temporal Cloud control plane.

Audit Logging answers "who, when, and what" questions about Temporal Cloud resources. These answers can help you evaluate the security of your organization, and they can provide information that you need to satisfy audit and compliance requirements.

info

Audit Logging does NOT capture data plane events, like Workflow Start, Workflow Terminate, Schedule Create, etc. Instead, explore the Export feature, which does let you send closed Workflow Histories to external storage.

Which integrations are supported by Audit Logging?​

Audit Logging supports both Amazon Kinesis and Google Cloud Pub/Sub streaming-data platforms.

Which events are supported by Audit Logging?​

  • Account
    • ChangeAccountPlanType: Change Account Plan Type
    • UpdateAccountAPI: Configure Audit Logging, Configure Observability Endpoint
  • User
    • CreateUserAPI: Create Users
    • DeleteUserAPI: Delete Users
    • InviteUsersAPI: Invite Users
    • SetUserNamespaceAccessAPI: Set User Namespace Access
    • UpdateIdentityNamespacePermissionsAPI: Update Identity Namespace Permissions
    • UpdateUserAPI: Update User Account-level Roles
    • UpdateUserNamespacePermissionsAPI: Update User Namespace Permissions
  • User Groups
    • CreateUserGroup: Create User Group
    • DeleteUserGroup: Delete User Group
    • SetUserGroupNamespaceAccess: Set User Group Namespace Access
    • UpdateUserGroup: Update User Group
  • Namespace
    • CreateNamespaceAPI: Create Namespace
    • DeleteNamespaceAPI: Delete Namespace
    • FailoverNamespacesAPI: Failover (for High Availability Namespaces)
    • RenameCustomSearchAttributeAPI: Rename Custom Search Attribute
    • UpdateNamespaceAPI: Update Namespace (includes change retention period, edit replicas, update authentication methods, update custom search attributes)
  • Nexus Endpoint
    • CreateNexusEndpoint: Create Nexus Endpoint
    • DeleteNexusEndpoint: Delete Nexus Endpoint
    • UpdateNexusEndpoint: Update Nexus Endpoint
  • API Keys
    • CreateAPIKey: Create API Key
    • DeleteAPIKey: Delete API Key
    • UpdateAPIKey: Update API Key
  • Service Accounts
    • CreateServiceAccount: Create Service Account
    • CreateServiceAccountAPIKey: Create Service Account API Key
    • DeleteServiceAccount: Delete Service Account
    • UpdateServiceAccount: Update Service Account
  • Namespace Export
    • CreateNamespaceExportSink: Create Namespace Export Sink
    • DeleteNamespaceExportSink: Delete Namespace Export Sink
    • UpdateNamespaceExportSink: Update Namespace Export Sink
    • ValidateNamespaceExportSink: Validate Namespace Export Sink

Audit Log format​

Audit Logs use the following JSON format:

{
  "emit_time": // Time the operation was recorded
  "level": // Level of the log entry, such as info, warning, or error
  "user_email":  // Email address of the user who initiated the operation
  "caller_ip_address": // Customer IP address in the X-Forwarded-For format
  "operation":  // Operation that was performed
  "details":  // Details of the operation
  "status": // Status, such as OK or ERROR
  "category":  // Category of the log entry: Admin or System
  "version": // Version of the log entry
  "log_id": // Unique ID of the log entry
  "principal": // Information about who initiated the operation
  "request_id": // Optional async request id set by the user when sending a request
}
note

The X-Forwarded-For format is a comma-separated list of IP addresses which should be evaluated from the last to the first, until meeting the first untrusted IP address of the list. This allows for instance to consider proxies in the path.

Temporal provides the caller IP address in that format to allow customers to identify a caller IP address even if one (or more proxies) are in the network path to reach Temporal Cloud.

Example of an Audit Log​

{"emit_time":"2023-10-24T08:19:41Z","level":"LOG_LEVEL_INFO","caller_ip_address":"10.1.2.3, 10.4.5.6","user_email":"user1@example.com","operation":"UpdateAccount","details":{"client_ca_fingerprints":["5bb99d14fa602f7d39b7d048674a2251"],"search_attribute_update":{}},"status":"OK","category":"LOG_CATEGORY_ADMIN","log_id":"0mc69c0323b871293ce231dd1c7fb634","principal":{"id":"988cb80b-d6be-4bb5-9c87-d09f93f58ed3","type":"user","name":"user1@example.com"}}
**********
{"emit_time":"2023-10-25T21:16:42Z","level":"LOG_LEVEL_INFO","caller_ip_address":"10.7.8.9","user_email":"user2@example.com","operation":"DeleteUser","details":{"target_users":["0b741c47-e093-47d1-9b74-f2359129f78f"],"search_attribute_update":{}},"status":"OK","category":"LOG_CATEGORY_ADMIN","log_id":"0mc69c0323b871293ce231dd1c7fb635","request_id":"445297d3-43a7-4793-8a04-1b1dd1999641","principal":{"id":"b160473e-e40d-4a81-90d1-f4218269e6e4","type":"user","name":"user2@example.com"}}
**********
{"emit_time":"2023-11-03T19:31:45Z","level":"LOG_LEVEL_INFO","caller_ip_address":"10.1.2.3, 10.10.11.12","user_email":"user3@example.com","operation":"InviteUsers","details":{"target_users":["user3@example.net"],"search_attribute_update":{}},"status":"OK","category":"LOG_CATEGORY_ADMIN","log_id":"0mc69c0323b871293ce231dd1c7fb636","principal":{"id":"35fdc757-9637-446b-b386-12ed475511ad","type":"user","name":"user3@example.com"}}
**********
{"emit_time":"2023-11-08T08:06:40Z","level":"LOG_LEVEL_INFO","caller_ip_address":"10.1.2.3, 10.4.5.6","user_email":"user1@example.com","operation":"UpdateUser","details":{"target_users":["user1@example.net"],"search_attribute_update":{}},"status":"OK","category":"LOG_CATEGORY_ADMIN","log_id":"0mc69c0323b871293ce231dd1c7fb637","request_id":"445297d3-43a7-4793-8a04-1b1dd1999640","principal":{"id":"988cb80b-d6be-4bb5-9c87-d09f93f58ed3","type":"user","name":"user1@example.com"}}
**********
{"emit_time":"2023-11-08T08:14:09Z","level":"LOG_LEVEL_INFO","caller_ip_address":"10.1.2.3, 10.4.5.6","user_email":"user1@example.com","operation":"UpdateNamespace","details":{"namespace":"audit-log-test.example-dev","client_ca_fingerprints":["f186d0bd971ff7d52dc6cc9d9b6f7644"],"search_attribute_update":{}},"status":"OK","category":"LOG_CATEGORY_ADMIN","log_id":"0mc69c0323b871293ce231dd1c7fb638","principal":{"id":"988cb80b-d6be-4bb5-9c87-d09f93f58ed3","type":"user","name":"user1@example.com"}}
**********
{"emit_time":"2023-11-08T09:20:22Z","level":"LOG_LEVEL_INFO","caller_ip_address":"10.1.2.3, 10.4.5.6","user_email":"user1@example.com","operation":"UpdateUserNamespacePermissions","details":{"namespace":"audit-log-test.example-dev","search_attribute_update":{}},"status":"OK","category":"LOG_CATEGORY_ADMIN","log_id":"0mc69c0323b871293ce231dd1c7fb639","principal":{"id":"988cb80b-d6be-4bb5-9c87-d09f93f58ed3","type":"user","name":"user1@example.com"}}
**********

How to configure Audit Logging​

Audit logging can be configured in AWS Kinesis or GCP Pub/Sub.

Consume an Audit Log​

How to consume an Audit Log

After you create an Audit Log sink, wait for the logs to flow into the stream. You should see the first logs 2–10 minutes after you configure the sink. Subsequent logs arrive every 2 minutes if any actions occurred during that 2-minute window.

note

You must configure and implement your own consumer of the stream.

How to troubleshoot Audit Logging​

The Audit Logging page of the Temporal Cloud UI provides the current status of an Audit Log sink.

  • If an error is detected, a summary of the error appears below the page title.
  • If the Audit Log sink is functioning normally, an On badge appears next to the page heading.

After an Admin Operation is performed, users can see Audit Log messages flow through the stream.

Upon successful configuration of the Audit Log sink and set up of a stream, you will receive events within the hour of setup. Temporal is able to retain Audit Log information for up to 30 days. To retrieve logs up to the past 30 days, you will need to file a request.

If you experience an issue with an Audit Log sink, we can provide the missing audit information. Open a support ticket to request assistance.

How to delete an Audit Log sink​

When you no longer need Audit Logging, you can delete the Audit Log sink.

  1. In the Temporal Cloud UI, select Settings.
  2. On the Settings page, select Integrations.
  3. In the Audit Logging card, select Configure Audit Logs.
  4. At the bottom of the Audit Logging page, choose Delete.

After you confirm the deletion, the Audit Log Sink is removed from your account and logs stop flowing to your stream.