Analyze events in custom event buses - EventBridge - Alibaba Cloud Documentation Center

When you publish custom events to EventBridge, you may need to query, filter, and trace those events across your system. Event analysis lets you run structured queries against all events in a custom event bus using key-value pair retrieval, GUI-based analysis, event tracing, and event source tracing.

To enable event analysis, bind a schema to your custom events. The schema describes the event structure and maps event fields to the analysis platform for structured queries and visualizations.

How it works

You can create and query only event schemas that conform to the OpenAPI 3.0 specification. The schema defines the fields in your event payload so the analysis platform can index and query them.

Bind a schema to custom events using one of two methods:

Method	How it works	When to use
Rule mapping	Bind the schema URI through an event rule in the EventBridge console.	You want a no-code setup through the console.
Push mapping	Set the `dataschema` parameter in the `PutEvents` API call to bind the schema URI at publish time.	You publish events programmatically and want to control schema binding in code.

Prerequisites

Before you begin, make sure you have:

An activated EventBridge service with the required permissions granted to a Resource Access Management (RAM) user. For more information, see Activate EventBridge and grant permissions to a RAM user
An Alibaba Cloud account with an AccessKey pair. Create or view your AccessKey pair on the Security Management page

Create a custom schema

Log on to the EventBridge console. In the left-side navigation pane, click Schemas.
In the top navigation bar, select the region.
On the Schemas page, click the Custom Schema Groups tab, then click Create Schema.

In the Create Schema panel, configure the following parameters and click OK.

Parameter	Description	Example
Schema ID	Name of the schema.	test
Schema Description	Description of the schema.	demo
Schema Content	Create Directly: Automatically generates JSON text that conforms to the OpenAPI 3.0 specification. Create Based on JSON: Generates a schema from a JSON sample that you provide.	Create Directly
Compatible Type	Whether to enable compatibility checks between schema versions. Default: no compatibility check.	No Compatibility Check

After the schema is created, verify the URI, version, format, and compatibility type on the Custom Schema Groups tab of the Schemas page.

Map the schema to events

Bind the schema to your custom events using one of the following methods.

Rule mapping

On the Event Buses page, click the custom event bus to manage. In the left-side navigation pane, click Event Rules, then click Create Rule.
In the Create Rule panel, complete the following steps:
1. In the Configure Basic Info step, set the Name and Description parameters and click Next Step.
2. In the Configure Event Pattern step, specify the custom event source to query and click Next Step.
3. In the Configure Targets step, set Service Type to Event Analysis and Mapping Method to Rule Mapping. Select the same Group Name, Schema ID, and Schema Version as the schema created in the previous step.
Click Create.

Push mapping

Add the dataschema parameter and the schema URI from the previous step to your SDK code, then push events. The following Java example shows the complete flow:

   import com.aliyun.eventbridge.EventBridge;
   import com.aliyun.eventbridge.EventBridgeClient;
   import com.aliyun.eventbridge.models.CloudEvent;
   import com.aliyun.eventbridge.models.Config;
   import com.aliyun.eventbridge.models.PutEventsResponse;
   import com.aliyun.eventbridge.util.EventBuilder;
   import com.google.gson.Gson;

   import java.net.URI;
   import java.util.ArrayList;
   import java.util.Date;
   import java.util.List;

   public class PutEventsSample {

       private EventBridge eventBridgeClient;

       public PutEventsSample() {
           Config authConfig = new Config();
           // Obtain the AccessKey ID from environment variables.
           authConfig.accessKeyId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
           // Obtain the AccessKey secret from environment variables.
           authConfig.accessKeySecret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
           // Specify the endpoint. For more information, see Regions and endpoints.
           authConfig.endpoint = "<your-endpoint>";
           eventBridgeClient = new EventBridgeClient(authConfig);
       }

       public void putEventsSample() {
           List<CloudEvent> cloudEventList = new ArrayList<>();
           CloudEvent cloudEvent = EventBuilder.builder()
               .withId("a5074581-7e74-4e4c-868f-47e7afdf****")
               .withSource(URI.create("acs.oss"))
               .withType("oss:ObjectCreated:PostObject")
               .withSubject("acs:oss:cn-hangzhou:{yourAccountId}:xls-papk/game_apk/123.jpg")
               .withTime(new Date())
               .withJsonStringData("{ \"E-Mail\": \"${email}\" }")
               .withAliyunEventBus("demo-bus")
               .build();
           // Set the schema URI obtained from the Create a custom schema step.
           cloudEvent.setDataschema("<schema-uri>");
           cloudEventList.add(cloudEvent);
           PutEventsResponse putEventsResponse = eventBridgeClient.putEvents(cloudEventList);
           System.out.println(new Gson().toJson(putEventsResponse));
       }

       public static void main(String[] args) {
           PutEventsSample sample = new PutEventsSample();
           try {
               sample.putEventsSample();
           } catch (Throwable e) {
               e.printStackTrace();
           }
       }
   }

Replace the following placeholders with actual values:

Placeholder	Description	Example
`<your-endpoint>`	EventBridge endpoint for your region	-
`<schema-uri>`	Schema URI from the previous step	-

On the Event Buses page, click the custom event bus to manage. In the left-side navigation pane, click Event Rules, then click Create Rule.
In the Create Rule panel, complete the following steps:
1. In the Configure Basic Info step, set the Name and Description parameters and click Next Step.
2. In the Configure Event Pattern step, specify the custom event source to query and click Next Step.
3. In the Configure Targets step, set Service Type to Event Analysis and Mapping Method to Push Mapping.
Click Create.

Query events

Log on to the EventBridge console. In the left-side navigation pane, choose Event Center > Event Analysis.
In the top navigation bar, select the region.
On the Event Analysis page, set the query parameters and click Query.

Required parameters

Parameter	Description
Event Bus	Name of the event bus to query.
Schema	Schema of the event type to query. For more information about Alibaba Cloud service event types, see Alibaba Cloud service event sources.

Optional parameters

Parameter	Description
Key-value Match	Filter events by key-value pairs. Specify one or more conditions using the operators listed below. Select AND or OR to the right of the Key-value Match parameter to specify the relationship between multiple key-value pairs.
Aggregate Function	Aggregate functions for data visualization. Each function maps to a line chart. Required for chart-based results.
Grouped By	Field by which to group events. Enter one or more event property fields.
Ordered By	Field by which to sort events in ascending or descending order, based on aggregate function results. You can enter one or more fields.
Time Range	Time range for the query.
Number of Events	Maximum number of events to return.

Key-value match operators

Operator	Behavior
`=`	Matches events where the key equals the value.
`!=`	Matches events where the key does not equal the value.
`exists`	Matches events where the key exists, regardless of value.
`does-not-exist`	Matches events where the key does not exist.

Analyze the results

View query results on the Aggregate Function and Table tabs of the Event Analysis page.

For details about event parameters in the results, see Analysis of the events in the system event bus.