Amazon CodeCatalyst is no longer open to new customers. Existing customers can continue to use the service as normal. For more information, see [How to migrate from CodeCatalyst](migration.md). # Monitoring events and API calls using logging In Amazon CodeCatalyst, management events for the space are collected by AWS CloudTrail and are logged in the trail for the billing account for the space. CloudTrail logging is the primary method to manage logging for CodeCatalyst events, and a secondary method is viewing event logging in CodeCatalyst. Events in the account are logged with the trail and designated bucket that is set up for the AWS account. The following diagram shows how all management events for the space are logged in CloudTrail for the billing account, while account connections/billing events and AWS resource events are logged in CloudTrail for the respective account. ![\[Diagram showing how event logging for spaces is managed\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/ipa/logging-codecatalyst.png) The diagram illustrates the following steps: 1. When a space is created, an AWS account is connected to the space and is designated as the billing account. The trail used is the trail that was created in CloudTrail for the billing account, where space events are logged. CloudTrail captures API calls and related events made by or on behalf of a CodeCatalyst space and delivers the log files to an S3 bucket that you specify. If the billing account changes to another AWS account, then space events are logged in the trail and bucket for that account. For more information about CodeCatalyst management events that are logged by CloudTrail, see [CodeCatalyst information in CloudTrail](ipa-logging-connections.md#info-in-cloudtrail). 1. Other accounts connected to the space, including the billing account, log a subset of events for account connections and billing events. CodeCatalyst workflows that generate account events for AWS resources deployed for that account are also logged in the trail and bucket for the AWS account. CloudTrail captures API calls and related events made by or on behalf of a CodeCatalyst space and delivers the log files to an S3 bucket that you specify. For more information about CodeCatalyst management events that are logged by CloudTrail, see [Accessing logged events using event logging](ipa-logging-connections.md). 1. You can also monitor CodeCatalyst actions in your space within a specific time in the space with the [https://docs.aws.amazon.com//cli/latest/reference/codecatalyst/list-event-logs.html](https://docs.aws.amazon.com//cli/latest/reference/codecatalyst/list-event-logs.html) command using the AWS CLI. For more information, see [the Amazon CodeCatalyst API Reference Guide](https://docs.aws.amazon.com/codecatalyst/latest/APIReference/Welcome.html). You must have the **Space administrator** role to call the list of events for CodeCatalyst actions in your space. For more information, see [Accessing logged events using event logging](ipa-logging-connections.md). **Note** `ListEventLogs` guarantees events for the last 30 days in a given space. You can also view and retrieve a list of management events over the last 90 days for CodeCatalyst in the AWS CloudTrail console by viewing **Event history**, or by creating a trail to create and maintain a record of events that extends past 90 days. For more information, see [Working with CloudTrail Event history](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html) and [Working with CloudTrail trails](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-getting-started.html). **Note** AWS resources that are deployed into connected accounts for CodeCatalyst workflows, are not logged as part of CloudTrail logging for the CodeCatalyst space. For example, CodeCatalyst resources include a space or project. AWS resources include an Amazon ECS service or Lambda function. You must configure CloudTrail logging separately for each AWS account where resources are deployed into. Here is one possible flow for event monitoring in CodeCatalyst. Mary Major is a **Space administrator** for a CodeCatalyst space and views all management events in CodeCatalyst for space-level and project-level resources in the space that are logged in CloudTrail. See [CodeCatalyst information in CloudTrail](ipa-logging-connections.md#info-in-cloudtrail) for example events that are logged in CloudTrail. For resources that are created in CodeCatalyst, such as Dev Environments, Mary views the **Event history** in the billing account for the space and investigates events where Dev Environments were created by project members in CodeCatalyst. The event provides the identity store IAM identity type and credentials for the AWS Builder ID for the user who created the Dev Environment. For resources that are created in AWS when deployed by workflows in CodeCatalyst, such as a Lambda function for a serverless deployment, the AWS account owner can view the event history for the trail associated with the separate AWS account (which is also a connected account to CodeCatalyst) for the workflow deploy action. To investigate further, Mary can also view events for all CodeCatalyst APIs in the space by using the [https://docs.aws.amazon.com//cli/latest/reference/codecatalyst/list-event-logs.html](https://docs.aws.amazon.com//cli/latest/reference/codecatalyst/list-event-logs.html) command in the AWS CLI. **Topics** + [Monitoring API calls by AWS accounts using AWS CloudTrail logging](ipa-logging-connections.md) + [Accessing logged events using event logging](ipa-logs.md) # Monitoring API calls by AWS accounts using AWS CloudTrail logging Amazon CodeCatalyst is integrated with AWS CloudTrail, a service that provides a record of actions taken by a user, role, or an AWS service. CloudTrail captures API calls made on behalf of CodeCatalyst in connected AWS accounts as events. If you create a trail, you can enable continuous delivery of CloudTrail events to an S3 bucket, including events for CodeCatalyst. If you don't configure a trail, you can still view the most recent events in the CloudTrail console in **Event history**. CodeCatalyst supports logging the following actions as events in CloudTrail log files: + Management events for CodeCatalyst spaces will be logged in the AWS account that is the designated billing account for the space. For more information, see [CodeCatalyst space events](#cloudtrail-logs-spaces-projects). **Note** Data events for CodeCatalyst spaces are accessible by using the CLI as detailed in [Accessing logged events using event logging](ipa-logs.md). + Events for resources that are used in CodeCatalyst workflow actions that occur in a connected AWS account will be logged as events in that AWS account. For more information, see [CodeCatalyst account connections and billing events](#cloudtrail-logs-connections). **Important** While multiple accounts can be associated with a space, CloudTrail logging for events in CodeCatalyst spaces and projects apply only for the billing account. The space billing account is your AWS account that is charged for CodeCatalyst resources beyond the AWS Free tier. Multiple accounts can be connected to a space, while only one account can be the designated billing account. The billing account or additional connected accounts for the space can have IAM roles that are used for deploying AWS resources and infrastructure, such as an Amazon ECS cluster or S3 bucket, from CodeCatalyst workflows. You can use the workflow YAML to identify the AWS account that you deployed to. **Note** AWS resources that are deployed into connected accounts for CodeCatalyst workflows, are not logged as part of CloudTrail logging for the CodeCatalyst space. For example, CodeCatalyst resources include a space or project. AWS resources include an Amazon ECS service or Lambda function. CloudTrail logging must be configured separately for each AWS account where resources are deployed into. CodeCatalyst logging in connected accounts includes the following considerations: + Access to CloudTrail events is managed with IAM in the connected account and not in CodeCatalyst. + Third-party connections, such as linking to a GitHub repository, will result in third-party resource names being recorded in CloudTrail logs. **Note** CloudTrail logging for CodeCatalyst events is at the space level and does not isolate events by project boundaries. For more information about CloudTrail, see the [AWS CloudTrail User Guide](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-user-guide.html). **Note** This section describes CloudTrail logging for all events logged in a logged in a CodeCatalyst space and the AWS accounts that are connected to CodeCatalyst. Additionally, to review all events logged in a CodeCatalyst space, you can also use the AWS CLI and the **aws codecatalyst list-event-logs** command. For more information, see [Accessing logged events using event logging](ipa-logs.md). ## CodeCatalyst space events Actions in CodeCatalyst for managing space-level and project-level resources are logged in the billing account for the space. For CloudTrail logging for a CodeCatalyst space, events are logged with the following considerations. + CloudTrail events apply across the entire space and are not scoped to any single project. + When you connect an AWS account to a CodeCatalyst space, loggable events for account connections will be logged in that AWS account. After you enable this connection, you cannot disable it. + When you connect an AWS account to a CodeCatalyst space and designate it as the billing account for the space, events will be logged in that AWS account. After you enable this connection, you cannot disable it. Events for space-level and project-level resources are logged only in the billing account. To change the CloudTrail destination account, update the billing account in CodeCatalyst. At the beginning of the next monthly billing cycle, the change takes effect for the new billing account in CodeCatalyst. After that, the CloudTrail destination account is updated. The following are examples of events in AWS that are related to actions in CodeCatalyst for managing space-level and project-level resources. The following APIs are released through the SDK and CLI. Events will be logged in the AWS account specified as the billing account for the CodeCatalyst space. + `[CreateDevEnvironment](https://docs.aws.amazon.com/codecatalyst/latest/APIReference/API_CreateDevEnvironment.html)` + `[CreateProject](https://docs.aws.amazon.com/codecatalyst/latest/APIReference/API_CreateProject.html)` + `[DeleteDevEnvironment](https://docs.aws.amazon.com/codecatalyst/latest/APIReference/API_DeleteDevEnvironment.html)` + `[GetDevEnvironment](https://docs.aws.amazon.com/codecatalyst/latest/APIReference/API_GetDevEnvironment.html)` + `[GetProject](https://docs.aws.amazon.com/codecatalyst/latest/APIReference/API_GetProject.html)` + `[GetSpace](https://docs.aws.amazon.com/codecatalyst/latest/APIReference/API_GetSpace.html)` + `[GetSubscription](https://docs.aws.amazon.com/codecatalyst/latest/APIReference/API_GetSubscription.html)` + `[ListDevEnvironments](https://docs.aws.amazon.com/codecatalyst/latest/APIReference/API_ListDevEnvironments.html)` + `[ListDevEnvironmentSessions](https://docs.aws.amazon.com/codecatalyst/latest/APIReference/API_ListDevEnvironmentSessions.html)` + `[ListEventLogs](https://docs.aws.amazon.com/codecatalyst/latest/APIReference/API_ListEventLogs.html)` + `[ListProjects](https://docs.aws.amazon.com/codecatalyst/latest/APIReference/API_ListProjects.html)` + `[ListSourceRepositories](https://docs.aws.amazon.com/codecatalyst/latest/APIReference/API_ListSourceRepositories.html)` + `[StartDevEnvironment](https://docs.aws.amazon.com/codecatalyst/latest/APIReference/API_StartDevEnvironment.html)` + `[StartDevEnvironmentSession](https://docs.aws.amazon.com/codecatalyst/latest/APIReference/API_StartDevEnvironmentSession.html)` + `[StopDevEnvironment](https://docs.aws.amazon.com/codecatalyst/latest/APIReference/API_StopDevEnvironment.html)` + `[StopDevEnvironmentSession](https://docs.aws.amazon.com/codecatalyst/latest/APIReference/API_StopDevEnvironmentSession.html)` + `[UpdateDevEnvironment](https://docs.aws.amazon.com/codecatalyst/latest/APIReference/API_UpdateDevEnvironment.html)` ## CodeCatalyst account connections and billing events The following are examples of events in AWS that are related to actions in CodeCatalyst for account connections or billing: + `AcceptConnection` + `AssociateIAMRoletoConnection` + `DeleteConnection` + `DissassociateIAMRolefromConnection` + `GetBillingAuthorization` + `GetConnection` + `GetPendingConnection` + `ListConnections` + `ListIAMRolesforConnection` + `PutBillingAuthorization` + `RejectConnection` ## CodeCatalyst information in CloudTrail CloudTrail is enabled on an AWS account when you create that account. When you connect that AWS account to a CodeCatalyst space, events for that space that occur in that AWS account are logged in CloudTrail logs in that AWS account. Loggable events in CodeCatalyst are recorded as CloudTrail events in CloudTrail logs in the connected account and in **Event history** in the CloudTrail console, along with other loggable AWS events in that account. Every event or log entry contains information about who generated the request. The identity information helps you determine the following: + Whether the request was made by a user with their AWS Builder ID. + Whether the request was made with root or AWS Identity and Access Management (IAM) user credentials. + Whether the request was made with temporary security credentials for a role or federated user. + Whether the request was made by another AWS service. For more information, see the [CloudTrail userIdentity element](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html). ## Accessing CloudTrail events For an ongoing record of events in your AWS account, including events for CodeCatalyst activity in the AWS account, create a trail. A *trail* enables CloudTrail to deliver log files to an S3 bucket. By default, when you create a trail in the console, the trail applies to all AWS Regions. The trail logs events from all Regions in the AWS partition and delivers the log files to the S3 bucket that you specify. Additionally, you can configure other AWS services to further analyze and act upon the event data collected in CloudTrail logs. For more information, see the following: + [Overview for creating a trail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html) + [CloudTrail supported services and integrations](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-aws-service-specific-topics.html) + [Configuring Amazon SNS notifications for CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/configure-sns-notifications-for-cloudtrail.html) + [Receiving CloudTrail log files from multiple regions](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/receive-cloudtrail-log-files-from-multiple-regions.html) and [Receiving CloudTrail log files from multiple accounts](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-receive-logs-from-multiple-accounts.html) A trail is a configuration that enables delivery of events as log files to an S3 bucket that you specify. CloudTrail log files contain one or more log entries. An event represents a single request from any source and includes information about the requested action, the date and time of the action, request parameters, and so on. CloudTrail log files aren't an ordered stack trace of the public API calls, so they don't appear in any specific order. ## Example CodeCatalyst account connections event in AWS The following example shows a CloudTrail log entry that demonstrates the `ListConnections` action. For an AWS account that is connected to the space, `ListConnections` is used to view all account connections to CodeCatalyst for this AWS account. The event will be logged in the AWS account specified in `accountId`, and the value of the `arn` will be the Amazon Resource Name (ARN) of the role used for the action. ``` { "eventVersion": "1.08", "userIdentity": { "type": "AssumedRole", "principalId": "AKIAI44QH8DHBEXAMPLE", "arn": "role-ARN", "accountId": "account-ID", "accessKeyId": "AKIAIOSFODNN7EXAMPLE", "sessionContext": { "sessionIssuer": { "type": "Role", "principalId": "AKIAI44QH8DHBEXAMPLE", "arn": "role-ARN", "accountId": "account-ID", "userName": "user-name" }, "webIdFederationData": {}, "attributes": { "creationDate": "2022-09-06T15:04:31Z", "mfaAuthenticated": "false" } } }, "eventTime": "2022-09-06T15:08:43Z", "eventSource": "account-ID", "eventName": "ListConnections", "awsRegion": "us-west-2", "sourceIPAddress": "192.168.0.1", "userAgent": "aws-cli/1.18.147 Python/2.7.18 Linux/5.4.207-126.363.amzn2int.x86_64 botocore/1.18.6", "requestParameters": null, "responseElements": null, "requestID": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 ", "eventID": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 ", "readOnly": true, "eventType": "AwsApiCall", "managementEvent": true, "recipientAccountId": "account-ID", "eventCategory": "Management" } ``` ## Example CodeCatalyst project resource event in AWS The following example shows a CloudTrail log entry that demonstrates the `CreateDevEnvironment` action. An AWS account that is connected to the space and is the designated billing account for the space is used for project-level events in the space, such as creating a Dev Environment. Under `userIdentity`, in the `accountId` field, this is the IAM Identity Center account ID (`432677196278`) that hosts the identity pool for all AWS Builder ID identities. This account ID contains the following information about the CodeCatalyst user for the event. + The `type` field indicates the type of IAM entity for the request. For CodeCatalyst events for space and project resources, this value is `IdentityCenterUser`. The `accountId` field specifies the account that owns the entity that was used to get credentials. + The `userId` field contains the AWS Builder ID identifier for the user. + The `identityStoreArn` field contains the role ARN for the identity store account and user. The `recipientAccountId` field contains the account ID for the billing account for the space, with an example value here of 111122223333. For more information, see the [CloudTrail userIdentity element](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html). ``` { "eventVersion": "1.09", "userIdentity": { "type": "IdentityCenterUser", "accountId": "432677196278", "onBehalfOf": { "userId": "user-ID", "identityStoreArn": "arn:aws:identitystore::432677196278:identitystore/d-9067642ac7" }, "credentialId": "ABCDefGhiJKLMn11Lmn_1AbCDEFgHijk-AaBCdEFGHIjKLmnOPqrs11abEXAMPLE" }, "eventTime": "2023-05-18T17:10:50Z", "eventSource": "codecatalyst.amazonaws.com", "eventName": "CreateDevEnvironment", "awsRegion": "us-west-2", "sourceIPAddress": "192.168.0.1", "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:102.0) Gecko/20100101 Firefox/102.0", "requestParameters": { "spaceName": "MySpace", "projectName": "MyProject", "ides": [{ "runtime": "public.ecr.aws/q6e8p2q0/cloud9-ide-runtime:2.5.1", "name": "Cloud9" }], "instanceType": "dev.standard1.small", "inactivityTimeoutMinutes": 15, "persistentStorage": { "sizeInGiB": 16 } }, "responseElements": { "spaceName": "MySpace", "projectName": "MyProject", "id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 " }, "requestID": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", "eventID": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", "readOnly": false, "eventType": "AwsApiCall", "managementEvent": true, "recipientAccountId": "111122223333", "sharedEventID": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", "eventCategory": "Management" } ``` **Note** In certain events, the user agent may not be known. In this case, CodeCatalyst will provide a value of `Unknown` in the `userAgent` field in the CloudTrail event. ## Querying your CodeCatalyst event trails You can create and manage queries for your CloudTrail logs using a query table in Amazon Athena. For more information about creating a query, see [Querying AWS CloudTrail logs](https://docs.aws.amazon.com/athena/latest/ug/cloudtrail-logs.html) in the *Amazon Athena User Guide*. # Accessing logged events using event logging When users perform actions in Amazon CodeCatalyst, these actions are recorded as events. You can use the AWS CLI to view logs of events in a space in a specified timeframe. You can view these events to review actions taken in the space, including the date and time of the actions, the name of the user who performed the action, and the IP address where the user made the request. **Note** Management events for a CodeCatalyst space are logged in CloudTrail for the connected billing account. For more information about CodeCatalyst management events that are logged by CloudTrail, see [CodeCatalyst information in CloudTrail](ipa-logging-connections.md#info-in-cloudtrail). In order to view a log of events for a space, you must have installed and configured the AWS CLI with a profile for CodeCatalyst, and you must have the **Space administrator** role for the space. For more information, see [Setting up to use the AWS CLI with CodeCatalyst](set-up-cli.md) and [Space administrator role](ipa-role-types.md#ipa-role-space-admin). **Note** To view logging for events that occur on behalf of CodeCatalyst in connected AWS accounts, or to view logging for events for space or project resources in the connected billing account, you can use AWS CloudTrail. For more information, see [Monitoring API calls by AWS accounts using AWS CloudTrail logging](ipa-logging-connections.md). 1. Open a terminal or command line and run the **aws codecatalyst list-event-logs** command, specifying: + The name of the space with the **--space-name** option. + The date and time when you want to start reviewing events, in coordinated universal time (UTC) timestamp format as specified in [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339#section-5.6), with the **--start-time** option. + The date and time when you want to stop reviewing events, in coordinated universal time (UTC) timestamp format as specified in [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339#section-5.6), with the **--end-time** option. + (Optional) The maximum number of results to return in a single response, with the **--max-results** option. If the number of results is larger than the number you specify, the response will include a `nextToken` element which you can use to return the next results. + (Optional) Limit the results to a specific event type you want returned, with the **--event-name** option. This example returns logged events in the space named *ExampleCorp* from the time period *2022-11-30* to *2022-12-01*, and that a maximum of *2* events be returned in the response. ``` aws codecatalyst list-event-logs --space-name ExampleCorp --start-time 2022-11-30 --end-time 2022-12-01 --event-name list-event-logs --max-results 2 ``` 1. If events occurred in this time frame, the command returns results similar to the following: ``` { "nextToken": "EXAMPLE", "items": [ { "id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", "eventName": "listEventLogs", "eventType": "AwsApiCall", "eventCategory": "MANAGEMENT", "eventSource": "manage", "eventTime": "2022-12-01T22:47:24.605000+00:00", "operationType": "READONLY", "userIdentity": { "userType": "USER", "principalId": "a1b2c3d4e5-678fgh90-1a2b-3c4d-e5f6-EXAMPLE11111" "userName": "MaryMajor" }, "requestId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE22222", "requestPayload": { "contentType": "application/json", "data": "{\"spaceName\":\"ExampleCorp\",\"startTime\":\"2022-12-01T00:00:00Z\",\"endTime\":\"2022-12-10T00:00:00Z\",\"maxResults\":\"2\"}" }, "sourceIpAddress": "127.0.0.1", "userAgent": "aws-cli/2.9.0 Python/3.9.11 Darwin/21.3.0 exe/x86_64 prompt/off command/codecatalyst.list-event-logs" }, { "id": "a1b2c3d4-5678-90ab-cdef-EXAMPLEaaaaa", "eventName": "createProject", "eventType": "AwsApiCall", "eventCategory": "MANAGEMENT", "eventSource": "manage", "eventTime": "2022-12-01T09:15:32.068000+00:00", "operationType": "MUTATION", "userIdentity": { "userType": "USER", "principalId": "a1b2c3d4e5-678fgh90-1a2b-3c4d-e5f6-EXAMPLE11111", "userName": "MaryMajor" }, "requestId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE33333", "requestPayload": { "contentType": "application/json", "data": "{\"spaceName\":\"ExampleCorp\",\"name\":\"MyFirstProject\",\"displayName\":\"MyFirstProject\"}" }, "responsePayload": { "contentType": "application/json", "data": "{\"spaceName\":\"ExampleCorp\",\"name\":\"MyFirstProject\",\"displayName\":\"MyFirstProject\",\"id\":\"a1b2c3d4-5678-90ab-cdef-EXAMPLE4444\"}" }, "sourceIpAddress": "192.0.2.23", "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:102.0) Gecko/20100101 Firefox/102.0" } ] } ``` 1. Run the **list-event-logs** command again with the **--next-token** option and the value of the returned token to retrieve the next set of logged events that match the request.