Event subscriptions provide a way to programmatically notify downstream systems of key events in your Tetra Data Platform (TDP) environment. By subscribing to specific TDP events, you can then automatically trigger custom apps and business processes to accomplish follow-on actions, such as the following:

• Notify a custom app when a file is uploaded to the TDP from a specific instrument type
• Alert scientists when a file is available for search
• Programmatically monitor Tetra Agent health
• Fuel workflow operational metrics and custom dashboards

Create an Event Subscription

Event subscriptions are delivered through Amazon EventBridge. To create an event subscription, you must first create an EventBridge event bus in your AWS account. The event bus contains rules that match incoming events and send them to targets for processing. Then, you can select the TDP events that you want the event bus to receive by configuring an event subscription on the Event Subscriptions page in the TDP user interface.

Step 1: Set Up an EventBridge Event Bus

To create an Amazon EventBridge event bus, do the following:

1. Sign in to the Amazon EventBridge console.

2. Create a custom event bus. For instructions, see Creating an Amazon EventBridge event bus in the AWS documentation.

   🚧

   IMPORTANT

   For subscribing to events across AWS accounts, make sure that you allow the AWS account where the TDP is running to put events into your target AWS account. To set up the required permissions, enter the following AWS Identity and Access Management (IAM) policy into the Resource-based policy section:

   {
    "Version": "2012-10-17",
    "Statement": [{
      "Sid": "AllowAccountToPutEvents",
     "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<AWS_ACCOUNT_ID_OF_TETRASCIENCE_DEPLOYMENT>:root"
      },
      "Action": "events:PutEvents",
      "Resource": "arn:aws:events:<MY_AWS_REGION>:<MY_AWS_ACCOUNT_ID>:event-bus/<MY_EVENT_BUS_NAME>"
    }]
   }
   

   To get the AWS account ID for your TDP deployment (<AWS_ACCOUNT_ID_OF_TETRASCIENCE_DEPLOYMENT>), contact your customer success manager (CSM).

3. Create rules for the event bus that specify what actions to take when EventBridge receives an event that matches the event patterns in the rule. For instructions, see Create a rule in Amazon EventBridge and Creating event patterns in the AWS documentation. For specific examples, see Event Pattern Examples.

4. On the Event bus details pane, copy the Event bus ARN (Amazon Resource Name). You will need the full event bus ARN to set up the subscription to the event bus in the TDP user interface.

Step 2: Configure an Event Subscription in the TDP

To select the TDP events that you want your event bus to receive, do the following:

1. Sign in to the TDP as a user with Admin permissions.
2. In the left navigation menu, choose Administration. Then, choose Event Subscriptions. The Event Subscriptions page appears.
3. Choose Create Event Subscription. The Create Event Subscription dialog appears.
4. For SUBSCRIPTION NAME, enter a name for the subscription.
5. To enable the subscription immediately after it's created, move the ENABLE SUBSCRIPTION toggle to the right. To keep the subscription inactive, move the toggle to the left.
6. For EVENTS, select the events that you want to subscribe to.
7. For EVENT BUS NAME enter the full Amazon Resource Name (ARN) of the EventBridge event bus that you created.
8. Choose Save.

Event Payloads

Agent events and file events each have their own standard JSON payload structures. The following are example event payloads for each type of event.

Agent Event Payloads

For a list of events that each Tetra Agent generates and their payloads, see Common Agent Events. For a list of Tetra File-Log Agent events and their payloads, see Tetra File-Log Agent Events.

File Event Payloads

All file-based events in the TDP use the following standard JSON payload structure:

📘

NOTE

Each file event's payload includes a unique "detail-type" key/value pair based on the AWS resource that generates the event. The following example shows a tetra.file.WorkflowSucceeded.v1 event from Amazon Kinesis Data Streams ("detail-type": "Event from aws:kinesis").

{
    "version": "0", # Event version number provided by TDP EventBridge
    "id": "2cb10de3-4d8c-1819-8300-56b86830be51", # Unique AWS ID
    "detail-type": "Event from aws:kinesis", # AWS resource type
    "source": "Pipe ts-test-development-file-events-to-tetrascience-events", # Event Subscription name
    "account": "012345678901", #AWS Destination account ID
    "time": "2023-12-12T15:25:26Z", # The event timestamp in ISO format UTC
    "region": "us-east-2", # AWS Region
    "resources": [], # Unused
    "detail": {
        "type": "tetra.file.WorkflowSucceeded.v1", # TDP event type
        "orgSlug": "tetra-test", # Org slug of the TDP organization where the event was generated
        "record": {
            "fileId": "5bbfefad-9f9f-4677-94f5-fbf3a6bf88bd",
            "fileKey": "tetra-test/6f49fk393kdk/IDS/test_file/0.json",
            "version":"X846ooooqvx493kd0fkd",
            "bucket": "ts-platform-dev-datalake", # Amazon S3 bucket where the file is stored
            "type": "s3file", # File type
            "category": "IDS", # File category in the TDP
            "traceId": "ba683c67-7518-4c71-9690-0da82f2e92b3",
            "source": {
                "type": "empower" # Data source
            },
            "metadata": {},
            "tags": [],
            "labels":
                {
                    "name": "project_id",
                    "value": "proj12345"
                }
            ]
        },
        "createdAt": "2023-12-10T13:25:26Z", # Timestamp of when the file event was created in ISO format UTC
        "workflowId": "4465a573-5e65-40bf-b2f5-b9a1b3d170b2", # ID of the TDP workflow that created the event
        "pipelineId": "df1f9835-376c-4899-bd93-17e116723e85" # ID of the pipeline that created the event
    }
}

Event Types

Event subscriptions currently support the following event types.

Event Pattern Examples

The following are example EventBridge event patterns for common event subscription use cases.

For more information about how to create custom event patterns, see Amazon EventBridge event patterns in the AWS documentation.

📘

NOTE

You can test event patterns by using the EventBridge Sandbox. For more information, see Testing an event pattern using the EventBridge Sandbox in the AWS documentation.

Alert When any File in Your Organization is Available for Search

{
  "detail": {
    "orgSlug": ["your-org"],
    "type": ["tetrascience.file.SearchIndexingSucceeded.v1"]
  }
}

Alert When an IDS File with the Label {software: Empower} in your organization is Available for Search

{
  "detail": {
    "orgSlug": ["your-org"],
    "type": ["tetrascience.file.SearchIndexingSucceeded.v1"],
    "record": {
      "file": {
        "category": ["IDS"],
        "labels": {
          "name": ["software"],
          "value": ["Empower"]
        }
      }
    }
  }
}

Monitor Agent Heartbeat Events in Your Organization

{
  "detail": {
    "orgSlug": ["your-org"],
    "type": ["tetrascience.agents.common.heartbeat.v1"]
}

Monitor for File-Log Agent Failure Events in Your Organization

{
  "detail": {
    "orgSlug": ["your-org"],
    "type": ["tetrascience.agents.filelog.archiveFileDeleteFailed.v1", "tetrascience.agents.filelog.fileArchiveFailed.v1", "tetrascience.agents.filelog.fileUploadFailed.v1", "tetrascience.agents.filelog.pathValidationFailed.v1", "tetrascience.agents.filelog.scanError.v1"]
}

Fuel Workflow Operational Metrics and Custom Dashboards Across Multiple Organizations

{
  "detail": {
    "orgSlug": ["your-org-1", "your-org-2"],
    "type": [{
      "prefix": "tetrascience.file.Workflow"
    }]
 }

📘

NOTE

For this setup to work, you must have access to both "your-org-1" and "your-org-2". You must also create a separate event subscription for each organization, and both event subscriptions must point to the event bus that this event rule belongs to.