Stream Lineage¶
To move forward with updates to mission-critical applications or answer questions on important subjects like data regulation and compliance, teams need an easy means of comprehending the big picture journey of data in motion.
Stream lineage provides a graphical UI of event streams and data relationships with both a bird’s eye view and drill-down magnification for answering questions like:
- Where did data come from?
- Where is it going?
- Where, when, and how was it transformed?
Answers to questions like these allow developers to trust the data they’ve found, and gain the visibility needed to make sure their changes won’t cause any negative or unexpected downstream impact. Developers can learn and make decisions quickly with live metrics and metadata inspection embedded directly within lineage graphs.
Note
If you are working with secured data:
- The following tutorial assumes that you have role-based access to the clusters and topics you need.
- The tutorial assumes that you have role-based access to stream lineage. If you do not have this access, stream lineage will not show up as an option on any screen.
- Developer roles do not have access to stream lineage views in and of themselves. To give a developer access to stream lineage, grant them an additional role with stream lineage access such as Operator at the cluster level. To learn more, see Access Control (RBAC) for Stream Lineage and Use Role-Based Access Control (RBAC) in Confluent Cloud.
First Look¶
What stream lineage shows¶
Stream lineage in Confluent Cloud is represented visually to show the movement of data from source to destination, and how it is transformed as it moves. The lineage graph always shows the activity of producers and consumers of data for the last 10 minutes.
How to access stream lineage views¶
There are multiple ways to get into the stream lineage view, as described in Summary of navigation paths. This example shows one path.
To view the stream lineage UIs:
Log on to Confluent Cloud.
Select an environment.
Select a cluster.
Select a topic.
Click See in Stream Lineage on the top right of the topic page.
Tip
If you do not see the option See in Stream Lineage, then you do not have the required permissions. To learn more, see Access Control (RBAC) for Stream Lineage.
The stream lineage for that topic is shown.

Tip
The stream lineage shown in this example is the result of setting up a data pipeline based on several ksqlDB query streams. If you haven’t set up a data pipeline yet, your lineage view may only show a single, lonely event node.
To get an interesting lineage like the one shown above, take a spin through the tutorial in the next section!
Tutorial¶
In order to really see stream lineage in action, you need to configure topics, producers, and consumers to create a data pipeline. Once you have events flowing into your pipeline, you can use stream lineage to inspect where data is coming from, what transformations are applied to it, and where it’s going.
Select an environment, cluster, and Schema Registry¶
Add an environment or select an existing one.
Add a cluster or select an existing one on which to run the demo.
If you create a new cluster:
- You must select a cluster type. You can choose any cluster type.
- Choose a cloud provider and region.
- Click Continue to review configuration and costs, usage limits, and uptime service level agreement (SLA)
Then click Launch Cluster
Enable a Schema Registry (if not already enabled) by navigating to the schemas page for your cluster and follow the prompts to choose a region and cloud provider.
The Schema Registry settings and information will be available on the Schema Registry tab for the environment.
Generate and save the Schema Registry API key and secret for this Schema Registry. (Save the key to use later on step 10 of this procedure.)
Tip
If you need help with these initial steps, see Quick Start for Confluent Cloud.
Create the “stocks” topic and generate data¶
(Optional) Create a topic named
stocks
.Tip
- This step is optional because adding the Datagen connector (as described in next steps) will automatically create the
stocks
topic if it does not exist. - To learn more about manually creating topics and working with them, see Create, Edit, and Delete Topics.
- This step is optional because adding the Datagen connector (as described in next steps) will automatically create the
Choose Connectors from the menu and select the Datagen source connector.
Add the Connect Datagen source connector to generate sample data to the
stocks
topic, using these settings:- Name:
StockSourceConnector
- Which topic do you want to send data to?:
stocks
- Output message format:
AVRO
- Quickstart:
STOCK_TRADES
- Max interval between messages:
1000
- Number of tasks for this connector:
1
You’ll also need to generate and save an API key and secret for this cluster, if you have not done so already.
- Name:
Click Next, review the settings for the connector, and click Launch to start sending data to the target topic.
The connector first shows as Provisioning, then Running when it is fully initiated.
Create a ksqlDB app¶
- Navigate to ksqlDB
- Click Create application myself.
- Select Global access and click Continue.
- Provide an application name, such as
ksqlDB_stocks_app
, and accept the defaults for the number of streaming units. - Click Launch application.
Tip
- Provisioning will take some time. In some cases, it can take up to an hour.
- By creating the ksqlDB app with global access, you avoid having to create specific ACLs for the app itself. With global access, the ksqlDB cluster is running with the same level of access to Kafka as the user who provisions ksqlDB. If you are interested in learning how to manage ACLs on a ksqlDB cluster with granular access, see Appendix A: Creating a ksqlDB app with granular access and assigning ACLs.
Verify your ksqlDB app is running¶
Return to the list of ksqlDB apps on the Cloud Console.
Your ksqlDB app should have completed Provisioning, and show a status of Up
.

Create persistent streams in ksqlDB to filter on stock prices¶
Navigate to the ksqlDB Editor and click into your ksqlDB app, ksqlDB_stocks_app
(ksqlDB_stocks_app > Editor), to create the following persistent streams.
Specify each query statement in the Editor and click Run query to start the query. You can click the Streams tab to view a list of running queries.
Create a stream for the
stocks
topic, then create a persistent stream that filters on stocks with price <= 100. This feed the results to thestocks_under_100
topic.You’ll need to specify and run three separate queries for this step. You start by creating the
stocks
stream, then add the filters to find and list stocks under $100. After each of these, click Run query, then clear the editor to specify the next statement.CREATE STREAM stocks WITH (KAFKA_TOPIC = 'stocks', VALUE_FORMAT = 'AVRO');
CREATE STREAM stocks_under_100 WITH (KAFKA_TOPIC='stocks_under_100', PARTITIONS=10, REPLICAS=3) AS SELECT * FROM stocks WHERE (price <= 100);
SELECT * FROM stocks_under_100 EMIT CHANGES;
When you have these running, click the Streams tab. You should have two new streams,
STOCKS
andSTOCKS_UNDER_100
. (The last statement is a transient query on the stream,STOCKS_UNDER_100
, to get some data onto the UI.)Create a persistent stream that filters on stocks to BUY, and feed the results to the
stocks_buy
topic.You’ll need to specify and run two separate queries for this step. After each of these, click Run query, then clear the editor to specify the next statement.
CREATE STREAM stocks_buy WITH (KAFKA_TOPIC='stocks_buy', PARTITIONS=10, REPLICAS=3) AS SELECT * FROM stocks WHERE side='BUY';
SELECT * FROM stocks_buy EMIT CHANGES;
Create a persistent stream that filters on stocks to SELL.
You’ll need to specify and run two separate queries for this step. After each of these, click Run query, then clear the editor to specify the next statement.
CREATE STREAM stocks_sell WITH (KAFKA_TOPIC='stocks_sell', PARTITIONS=10, REPLICAS=3) AS SELECT * FROM stocks WHERE side='SELL';
SELECT * FROM stocks_sell EMIT CHANGES;
When you have completed these steps, click the ksqlDB > Streams tab. You should have four persistent ksqlDB query streams:
STOCKS
STOCKS_BUY
STOCKS_SELL
STOCKS_UNDER_100

These streams will have associated topics and schemas listed on those pages, respectively.

Consume events from the “stocks” topic¶
Now, set up a consumer using the Confluent Cloud CLI to consume events from your stocks
topic.
Log on to the Confluent Cloud CLI. (Provide username and password at prompts.)
confluent login --url https://confluent.cloud
List the environments to verify you are on the environment.
ccloud environment list
If needed, re-select the environment you’ve been using for this demo.
ccloud environment use <ENVIRONMENT_ID>
List the clusters to verify you are on the right cluster.
ccloud kafka cluster list
If needed, re-select the cluster you’ve been using for this demo.
ccloud kafka cluster use <KAFKA_CLUSTER_ID>
Create Kafka API credentials for the consumer.
Create an API key.
ccloud api-key create --resource <KAFKA_CLUSTER_ID>
Use the API key.
ccloud api-key use <API_KEY> --resource <KAFKA_CLUSTER_ID>
Alternatively, you can store the key.
ccloud api-key store --resource <KAFKA_CLUSTER_ID>
Run a CLI consumer.
ccloud kafka topic consume stocks_buy --value-format avro --group buy_group
When prompted, provide the Schema Registry API key you generated in the first steps.
You should see the consumer data being generated to the consumer at the command line, for example:
Vickys-MacBook-Pro:~ vicky$ ccloud kafka topic consume stocks_buy --value-format avro --group buy_group Enter your Schema Registry API key: ***************** Enter your Schema Registry API secret: **************************************************************** Starting Kafka Consumer. ^C or ^D to exit {"SIDE":{"string":"BUY"},"QUANTITY":{"int":959},"SYMBOL":{"string":"ZVZZT"},"PRICE":{"int":704},"ACCOUNT":{"string":"XYZ789"},"USERID":{"string":"User_8"}} {"ACCOUNT":{"string":"ABC123"},"USERID":{"string":"User_1"},"SIDE":{"string":"BUY"},"QUANTITY":{"int":1838},"SYMBOL":{"string":"ZWZZT"},"PRICE":{"int":405}} {"QUANTITY":{"int":2163},"SYMBOL":{"string":"ZTEST"},"PRICE":{"int":78},"ACCOUNT":{"string":"ABC123"},"USERID":{"string":"User_8"},"SIDE":{"string":"BUY"}} {"PRICE":{"int":165},"ACCOUNT":{"string":"LMN456"},"USERID":{"string":"User_2"},"SIDE":{"string":"BUY"},"QUANTITY":{"int":4675},"SYMBOL":{"string":"ZJZZT"}} {"QUANTITY":{"int":1702},"SYMBOL":{"string":"ZJZZT"},"PRICE":{"int":82},"ACCOUNT":{"string":"XYZ789"},"USERID":{"string":"User_7"},"SIDE":{"string":"BUY"}} {"ACCOUNT":{"string":"LMN456"},"USERID":{"string":"User_9"},"SIDE":{"string":"BUY"},"QUANTITY":{"int":2982},"SYMBOL":{"string":"ZVV"},"PRICE":{"int":643}} {"SIDE":{"string":"BUY"},"QUANTITY":{"int":3687},"SYMBOL":{"string":"ZJZZT"},"PRICE":{"int":514},"ACCOUNT":{"string":"ABC123"},"USERID":{"string":"User_5"}} {"USERID":{"string":"User_5"},"SIDE":{"string":"BUY"},"QUANTITY":{"int":289},"SYMBOL":{"string":"ZJZZT"},"PRICE":{"int":465},"ACCOUNT":{"string":"XYZ789"}} ...
Explore the data pipeline in stream lineage¶
Stream data quick tour¶
With the producers and consumers up and running, you can use stream lineage to visualize and explore the flow of data from the source connector
to the STOCKS topic, where queries filter the data on specified limits and generate lists to your three topics:
- STOCKS_BUY
- STOCKS_SELL
- STOCKS_UNDER_100
Search for stocks topic on the search box.
Click See in Stream Lineage on the top right of the stocks topic page.
The stream lineage for the
stocks
topic is shown.Hover on a node for a high level description of the data source and throughput.
This example shows a ksqlDB query node
The thumbnail in this case shows:
- Mode and type: persistent stream
- Total number of bytes in and out of the flow for the last 10 minutes
- Total number of messages in and out of the flow for the last 10 minutes
This example shows a topic node:
The thumbnail in this case shows:
- Topic name
- Schema format (can be Avro, Protobuf, or JSON schema)
- Number of partitions for the topic
- Total number of bytes into the topic during the last 10 minutes
- Total number of messages received by the topic in the last 10 minutes
Click a node to inspect.
Return to the diagram, and hover on an edge to get a description of the flow between the given nodes.
Click the edge to inspect.
Tabs on node drilldown to inspect queries¶
The stream lineage inspect panel surfaces details and metrics about the queries based on the nodes you select. The tabs available and details shown will vary, depending on the query. For example:
Overview tab - Shows per topic throughput, along with bytes consumed and produced.
Messages tab - Shows the list of messages the topic received.
Schema tab - Shows a view-only copy of the schema for the topic. An editable version is available directly from the topic (see Manage Schemas in Confluent Cloud).
Query tab - Shows a view-only copy of the persistent query that is sending results to the topic. (For details on stream processing, see the Section 2: Add ksqlDB to the cluster and ksqlDB Stream Processing.)
Try this¶
- Click the stocks topic node, and scroll through the message throughput timelines on the Overview tab, then click Edit topic to go directly to the topic.
- Click the stocks_buy topic node, then click the Schema tab to view its associated schema.
- Click a query, such as stocks_buy query, and click the Schema tab. This shows you a menu style view of the same schema because the schema associated with the stocks_buy topic is coming from the stocks_buy query.
- To verify this, click View query to link to the ksqlDB_stocks_app, then click the Flow tab under that app, and click stocks_buy on that diagram. (Note that you also can visualize a data flow particular to that query from directly within the ksqlDB app, but not the combined flows of all queries to all topics, as is shown on stream lineage.)
Hide or Show Internal Topics¶
From any stream lineage graph view, you have the option to hide or show internal (system) topics. System topics are those that manage and track Confluent Cloud metadata, such as replication factors, partition counts, and so forth. Typically, this system metadata is of less interest than data related your own topics, and you’ll want to hide it.

Browsing the Diagram View¶
Set the Diagram to a Point in Time¶
Important
This feature is available as a preview feature. A preview feature is a component of Confluent Cloud that is being introduced to gain early feedback. This feature can be used for evaluation and non-production testing purposes or to provide feedback to Confluent. Your comments, questions, and suggestions are encouraged and can be submitted to stream-governance-preview@confluent.io.
By default, graphs represent the last 10 minutes of data flowing through the system. You can navigate and search the graphs in this default time window, or set a specific time window. These settings apply to all data on the cluster, whether that data is currently on-screen or not.
Pre-set windows are available for:
- Last 10 minutes
- Last 30 minutes
- Last 1 hour
- Last 4 hours
- Last 8 hours
- Last 12 hours
- Last 24 hours (maximum size of a pre-set time window)
You can also set a custom date and time window for your search, going back 7 days for a selected 1 hour block.
The graphs, nodes, and available data will change depending on the selected time window. For example, a custom setting to show data only from last Friday from 6:00-7:00 AM will not show streams created later in the week. Similarly, the graph search is dependent on the time window setting, and will not find data that isn’t available in the current time window.
Search the Graph¶
Important
This feature is available as a preview feature. A preview feature is a component of Confluent Cloud that is being introduced to gain early feedback. This feature can be used for evaluation and non-production testing purposes or to provide feedback to Confluent. Your comments, questions, and suggestions are encouraged and can be submitted to stream-governance-preview@confluent.io.
You can search the graph for partial or full names of entities. The search finds topic names, connector names, ksqlDB query names, consumer groups, and producer client IDs. The search spans globally across the cluster, not just on-screen nodes in the current diagram.
Keep in mind that the search applies to data available across the cluster for the selected time window.
To execute a graph search, click into the Search bar and type a name (such as buy
in this example).
Next, select a search result by clicking it (for example STOCKS_BUY
).
The drilldown for that entity is displayed.
Export a Lineage Diagram¶
To export the current diagram, click the Export icon on the lower right tool panel.
Reset the View¶
To reset the view to center on the entity that is the original focus of the diagram,
click the Reset icon on the lower right tool panel.
Tip
Reset view is only applicable when you launch the lineage diagram from within an entity, such as a topic, ksqlDB table or stream, producer, consumer, and so forth. It is not applicable if you launch the lineage diagram from the left menu or dashboard because that is a global view, not centered on any specific node to begin with.
Zoom In or Out¶
Use the + and - buttons on the lower right tool panel to zoom in or zoom out on the lineage diagram.
Traverse the Diagram¶
To explore the diagram, click, hold, and drag the cursor, or use analogous actions such as three-finger drag on a Mac trackpad.
All Streams¶
Click All Streams on the lower right of a diagram to view cards representing the data flows.
The default view shows Stream 1.

Click another card to focus in on a particular stream, for example Stream 2. The diagram updates to show only the selected stream.

Understanding Data Nodes¶
Consumers and producers are automatically grouped; that is, a group of consumers or producers is represented as a single node that expands upon drilldown to show the client IDs.
Understanding Node Groups¶
In cases where you have a threshold number of nodes of the same type in a workflow (24 or more like nodes), stream lineage collapses these into a single node group to save screen real estate and improve navigation. This grouping is purely for visual display of like nodes that are processing data to or from the same connection point.
To drill down on the individual nodes represented by a node group:
Click the composite node (node group) to display the individual nodes on the right.
Select a node from the list on the right to inspect details of that node.
Automatic visual grouping of like nodes applies to any node type, but producers and consumers are the most common as there is a tendency to employ large numbers of these.
Understanding Edges¶
Edge thumbnails and drilldowns describe the flow between the given nodes. They show:
- The node where the data came from
- The node where the data is going to
- Bytes transfered
- Number of messages transferred
Tip
The relative thickness of an edge indicates the amount of data that is moving through the connected nodes during the selected time range, also known as throughput. Thicker edges have a higher throughput than thinner edges. To get specific throughput numbers, use the drilldowns.
Hovering on an edge gives you the thumbnail.
Drilldown on an edge provides the tab view.
Access Control (RBAC) for Stream Lineage¶
If Role-Based Access Control (RBAC) is configured on your clusters, you must make sure you have access to the appropriate resources, such as clusters, topics, and features such as stream lineage views. This section provides a summary of roles related to stream lineage access.
The following roles have full access to stream lineage views:
Role View Scope Admin Scope OrganizationAdmin All All EnvironmentAdmin Organization, Support Plan, Users All clusters in the environment, Schema Registry, Networking CloudClusterAdmin Organization, Environment, Support Plan, Users, Schema Registry Specified Cluster, Topics, ksqlDB applications, Connectors, Schema Subjects Operator Organization, Environment, Cluster N/A Developer roles (DeveloperManage, DeveloperRead, and DeveloperWrite) do not have access to stream lineage in and of themselves. To give developers stream lineage access, grant them an additional role from the above table with appropriate scope for need-to-know; such as Operator role at the cluster level.
To learn more, see Use Role-Based Access Control (RBAC) in Confluent Cloud.
Appendix A: Creating a ksqlDB app with granular access and assigning ACLs¶
As an alternative to creating the ksqlDB app with global access, you can create the app with granular access, assign a service account to it, and then create ACLs limited specifically to your ksqlDB app. There may be cases where you want to limit access to the ksqlDB cluster to specific topics or actions.
Navigate to ksqlDB
Click Create application myself.
Select Granular access and click Continue.
Under Create a service account:
- Select Create a new one (unless you already have an account you want to use).
- Provide a new service account name and description, such as
stocks_trader
ksqlDB_stocks_app
. - Check the box to add required ACLs when the ksqlDB app is created.
Provide access to the
stocks
topic (this should already be selected), and click Continue.Create the ACLs for your ksqlDB app as follows (skip this step if you have done this previously for this app).
Log on to the Confluent Cloud CLI. (Provide username and password at prompts.)
confluent login --url https://confluent.cloud
List the environments to get the environment ID.
ccloud environment list
Select the environment you’ve been using for this demo.
ccloud environment use <ENVIRONMENT_ID>
List the clusters to get the right cluster ID.
ccloud kafka cluster list
Select the cluster you’ve been using for this demo.
ccloud kafka cluster use <KAFKA_CLUSTER_ID>
List the ksqlDB apps to get the ID for your app.
ccloud ksql app list
Run this command to get the service account ID.
ccloud ksql app configure-acls <KSQL_APP_ID> * --cluster <KAFKA_CLUSTER_ID> --dry-run
Copy the service account ID (after
User:<SERVICE_ACCOUNT_ID>
in the output).Allow READ access to all topics on the ksql app for your service account ID.
ccloud kafka acl create --allow --service-account <SERVICE_ACCOUNT_ID> --operation READ --topic '*'
Allow WRITE access to all topics on the ksql app for your service account ID.
ccloud kafka acl create --allow --service-account <SERVICE_ACCOUNT_ID> --operation WRITE --topic '*'
Allow CREATE access for all topics on the ksql app for your service account ID.
ccloud kafka acl create --allow --service-account <SERVICE_ACCOUNT_ID> --operation CREATE --topic '*'