Skip to main content

Audit Logging - Temporal Cloud feature guide

Audit Logging is a feature of Temporal Cloud that provides forensic access information at the account level, the user level, Namespace level, and the Nexus Endpoint level.

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.

Which integrations are supported by Audit Logging?​

Audit Logging supports the Amazon Kinesis streaming-data platform.

Which events are supported by Audit Logging?​

Audit Logging supports Admin Operation events as well as API Key Create, Update, and Delete events.

Please note that Audit Logging only captures operations in the Temporal Cloud control plane and not the data plane. This means events such as Workflow Start, Workflow Terminate, Schedule Create, etc. won't be logged. Instead, explore the Export feature, which does let you send closed Workflow Histories to external storage.

Admin Operation events​

The following list specifies both the supported events and the Temporal APIs that emit the logs.

  • Account
    • Configure Audit Logging: UpdateAccount
    • Configure observability: UpdateAccount
  • User
    • Create user invitations: InviteUsers
    • Delete users: DeleteUser
    • Update user account-level Roles: UpdateUser
    • Update user Namespace permissions: UpdateUserNamespacePermissions
    • Log in user: UserLogin
  • Namespace
    • Create Namespace: CreateNamespace
    • Update Namespace: UpdateNamespace
    • Delete Namespace: DeleteNamespace
    • Add or update certificates or certificate filters: UpdateNamespace
    • Add custom Search Attributes: UpdateNamespace
    • Rename custom Search Attribute: RenameCustomSearchAttribute
    • Request increase in Retention Period: UpdateNamespace
  • Multi-region Namespace
    • Failover Namespace: FailoverNamespace
  • Nexus Endpoint
    • Create Nexus Endpoint: CreateNexusEndpoint
    • Update Nexus Endpoint: UpdateNexusEndpoint
    • Delete Nexus Endpoint: DeleteNexusEndpoint

API Key Operation events​

The following list specifies both the supported events and the Temporal APIs that emit the logs for API Key Operations:

  • Create API Key: CreateAPIKey
  • Delete API Key: DeleteAPIKey
  • Update API Key: UpdateAPIKey

Audit Log format​

The log sent to the stream is JSON in the following 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​

The following example shows the contents 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 both AWS Kinesis

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.