Skip to main content
Version: Next

Transport

Tip: See current list of all supported transports.

HTTP​

Allows sending events to HTTP endpoint, using ApacheHTTPClient.

Configuration​

  • type - string, must be "http". Required.
  • url - string, base url for HTTP requests. Required. A unix:// url (e.g. unix:///var/run/some.socket) sends events over a Unix Domain Socket instead of TCP (requires Java 16 or later) — see Unix Domain Socket below.
  • endpoint - string specifying the endpoint to which events are sent, appended to url. Optional, default: /api/v1/lineage.
  • urlParams - dictionary specifying query parameters send in HTTP requests. Optional.
  • timeoutInMillis - integer specifying timeout (in milliseconds) value used while connecting to server. Optional, default: 5000.
  • auth - dictionary specifying authentication options. Optional, by default no authorization is used. If set, requires the type property.
    • type - string specifying value for one of the out-of-the-box available authentication methods (apiKey or jwt), or the fully qualified class name of your TokenProvider. Required if auth is provided.
    • Configuration options for api_key authentication:
      • apiKey - string setting the Authentication HTTP header as the Bearer. Required if type is api_key.
    • Configuration options for jwt authentication are documented in the JWT Token Provider section.
  • headers - dictionary specifying HTTP request headers. Optional.
  • compression - string, name of algorithm used by HTTP client to compress request body. Optional, default value null, allowed values: gzip. Added in v1.13.0.

Behavior​

Events are serialized to JSON, and then are send as HTTP POST request with Content-Type: application/json.

Unix Domain Socket​

Requires Java 16 or later

Unix Domain Socket support uses the JDK-native UDS APIs introduced in Java 16 (JEP 380). It is available only when running on Java 16 or later. On an older JVM, configuring a unix:// url fails fast with a clear error, while http(s):// urls keep working on every supported Java version.

When url uses the unix:// scheme, the transport sends events over a Unix Domain Socket instead of a TCP connection. This is useful when the collector is reachable only through a local socket — for example a sidecar or daemon exposing an HTTP endpoint over a socket on a Kubernetes node.

The path component of the URL is the socket path (unix:///var/run/some.socket → /var/run/some.socket). The request is issued against a placeholder http://localhost/<endpoint> and tunneled over the socket, so endpoint, headers, auth, compression, urlParams and timeoutInMillis behave exactly as they do for a regular http(s) url. TLS is not applied over the local socket.

Because it builds on the JDK-native UDS support, this feature needs no extra dependencies.

Examples​

Anonymous connection:

transport:
  type: http
  url: http://localhost:5000

Unix Domain Socket connection:

transport:
  type: http
  url: unix:///var/run/some.socket
  endpoint: /api/v1/lineage

With authorization:

transport:
  type: http
  url: http://localhost:5000
  auth:
    type: api_key
    api_key: f38d2189-c603-4b46-bdea-e573a3b5a7d5

Full example:

transport:
  type: http
  url: http://localhost:5000
  endpoint: /api/v1/lineage
  urlParams:
    param0: value0
    param1: value1
  timeoutInMillis: 5000
  auth:
    type: api_key
    api_key: f38d2189-c603-4b46-bdea-e573a3b5a7d5
  headers:
    X-Some-Extra-Header: abc
  compression: gzip

JWT Token Provider​

The JwtTokenProvider is an authentication provider that exchanges an API key for a JWT token via a POST endpoint. This is useful for services that require OAuth-style authentication where you need to obtain a token before making API requests.

Configuration​

When using JWT authentication with HTTP transport, configure the auth section as follows:

  • type - string, must be "jwt". Required.
  • apiKey - string, the API key used to obtain the JWT token. Required.
  • tokenEndpoint - string, the URL endpoint for token generation. Required.
  • tokenFields - array of strings, JSON field names to search for the token in the response. The provider tries each field in order. Optional, default: ["token", "access_token"].
  • expiresInField - string, JSON field name containing the token expiration time in seconds. Optional, default: "expires_in".
  • grantType - string, OAuth grant type parameter sent in the token request. Optional, default: "urn:ietf:params:oauth:grant-type:jwt-bearer".
  • responseType - string, OAuth response type parameter sent in the token request. Optional, default: "token".
  • tokenRefreshBuffer - integer, number of seconds before token expiry to trigger a refresh. Optional, default: 120.
Behavior​
  • The provider sends a POST request with URL-encoded form data containing the API key and OAuth parameters.
  • The response is expected to be JSON containing the JWT token and optionally an expiration time.
  • Tokens are cached and automatically refreshed before expiration (default: 120 seconds before expiry, configurable via tokenRefreshBuffer).
  • If no expiration is provided in the response, the provider attempts to extract it from the JWT payload's exp claim.
  • The provider supports multiple JSON field names for the token, trying each in order until a match is found.
  • Field matching is case-insensitive and handles both snake_case and camelCase variations (e.g., expires_in matches expiresIn).
Examples​

Standard OAuth configuration:

transport:
  type: http
  url: https://api.example.com
  auth:
    type: jwt
    apiKey: your-api-key
    tokenEndpoint: https://auth.example.com/token

With custom field names:

transport:
  type: http
  url: https://api.example.com
  auth:
    type: jwt
    apiKey: your-api-key
    tokenEndpoint: https://auth.example.com/token
    tokenFields: ["access_token", "token"]
    expiresInField: expires_in

IBM Cloud IAM configuration:

transport:
  type: http
  url: https://api.example.com
  auth:
    type: jwt
    apiKey: your-ibm-api-key
    tokenEndpoint: https://iam.cloud.ibm.com/identity/token
    grantType: urn:ibm:params:oauth:grant-type:apikey
    responseType: cloud_iam

Kafka​

If a transport type is set to kafka, then the below parameters would be read and used when building KafkaProducer. This transport requires the artifact org.apache.kafka:kafka-clients:3.1.0 (or compatible) on your classpath.

Configuration​

  • type - string, must be "kafka". Required.

  • topicName - string specifying the topic on what events will be sent. Required.

  • properties - a dictionary containing a Kafka producer config as in Kafka producer config. Required.

  • localServerId - deprecated, renamed to messageKey since v1.13.0.

  • messageKey - string, key for all Kafka messages produced by transport. Optional, default value described below. Added in v1.13.0.

    Default values for messageKey are:

    • run:{rootJob.namespace}/{rootJob.name} - for RunEvent with parent facet containing link to root job
    • run:{parentJob.namespace}/{parentJob.name} - for RunEvent with parent facet
    • run:{job.namespace}/{job.name} - for RunEvent
    • job:{job.namespace}/{job.name} - for JobEvent
    • dataset:{dataset.namespace}/{dataset.name} - for DatasetEvent

Behavior​

Events are serialized to JSON, and then dispatched to the Kafka topic.

Notes​

It is recommended to provide messageKey if Job hierarchy is used. It can be any string, but it should be the same for all jobs in hierarchy, like Airflow task -> Spark application -> Spark task runs.

Examples​

transport:
  type: kafka
  topicName: openlineage.events
  properties:
    bootstrap.servers: localhost:9092,another.host:9092
    acks: all
    retries: 3
    key.serializer: org.apache.kafka.common.serialization.StringSerializer
    value.serializer: org.apache.kafka.common.serialization.StringSerializer
  messageKey: some-value

Notes: It is recommended to provide messageKey if Job hierarchy is used. It can be any string, but it should be the same for all jobs in hierarchy, like Airflow task -> Spark application.

Default values are:

  • run:{rootJob.namespace}/{rootJob.name} - for RunEvent with parent facet containing link to root job
  • run:{parentJob.namespace}/{parentJob.name}/{parentRun.id} - for RunEvent with parent facet
  • run:{job.namespace}/{job.name}/{run.id} - for RunEvent
  • job:{job.namespace}/{job.name} - for JobEvent
  • dataset:{dataset.namespace}/{dataset.name} - for DatasetEvent

Console​

This straightforward transport emits OpenLineage events directly to the console through a logger. No additional configuration is required.

Behavior​

Events are serialized to JSON. Then each event is logged with INFO level to logger with name ConsoleTransport.

Notes​

Be cautious when using the DEBUG log level, as it might result in double-logging due to the OpenLineageClient also logging.

Configuration​

  • type - string, must be "console". Required.

Examples​

transport:
  type: console

File​

Designed mainly for integration testing, the FileTransport emits OpenLineage events to a given file.

Configuration​

  • type - string, must be "file". Required.
  • location - string specifying the path of the file. Required.

Behavior​

  • If the target file is absent, it's created.
  • Events are serialized to JSON, and then appended to a file, separated by newlines.
  • Intrinsic newline characters within the event JSON are eliminated to ensure one-line events.

Notes for Yarn/Kubernetes​

This transport type is pretty useless on Spark/Flink applications deployed to Yarn or Kubernetes cluster:

  • Each executor will write file to a local filesystem of Yarn container/K8s pod. So resulting file will be removed when such container/pod is destroyed.
  • Kubernetes persistent volumes are not destroyed after pod removal. But all the executors will write to the same network disk in parallel, producing a broken file.

Examples​

transport:
  type: file
  location: /path/to/your/file

Composite​

The CompositeTransport is designed to combine multiple transports, allowing event emission to several destinations. This is useful when events need to be sent to multiple targets, such as a logging system and an API endpoint. The events are delivered sequentially - one after another in a defined order.

Configuration​

  • type - string, must be "composite". Required.
  • transports - a list or a map of transport configurations. Required.
  • continueOnFailure - boolean flag, determines if the process should continue even when one of the transports fails. Default is true.
  • withThreadPool - boolean flag, determines if a thread pool for parallel event emission should be kept between event emissions. Default is true.

Behavior​

  • The configured transports will be initialized and used in sequence (sorted by transport name) to emit OpenLineage events.
  • If continueOnFailure is set to false, a failure in one transport will stop the event emission process, and an exception will be raised.
  • If continueOnFailure is true, the failure will be logged, but the remaining transports will still attempt to send the event.

Notes for Multiple Transports​

The composite transport can be used with any OpenLineage transport (e.g. HttpTransport, KafkaTransport, etc). Ideal for scenarios where OpenLineage events need to reach multiple destinations for redundancy or different types of processing.

The transports configuration can be provided in two formats:

  1. A list of transport configurations, where each transport may optionally include a name field.
  2. A map of transport configurations, where the key acts as the name for each transport. The map format is particularly useful for configurations set via environment variables or Java properties, providing a more convenient and flexible setup.
Why are transport names used?​

Transport names are not required for basic functionality. Their primary purpose is to enable configuration of composite transports via environment variables, which is only supported when names are defined.

Examples​

transport:
  type: composite
  continueOnFailure: true
  transports:
    - type: http
      url: http://example.com/api
      name: my_http
    - type: kafka
      topicName: openlineage.events
      properties:
        bootstrap.servers: localhost:9092,another.host:9092
        acks: all
        retries: 3
        key.serializer: org.apache.kafka.common.serialization.StringSerializer
        value.serializer: org.apache.kafka.common.serialization.StringSerializer
      messageKey: some-value
      continueOnFailure: true

Transform​

The TransformTransport is designed to enable event manipulation before emitting the event. Together with CompositeTransport, it can be used to send different events into multiple backends.

Configuration​

  • type - string, must be "transform". Required.
  • transformerClass - class name of the event transformer. Class has to implement io.openlineage.client.transports.transform.EventTransformer interface and provide public no-arg constructor. Class needs to be available on the classpath. Required.
  • transformerProperties - Extra properties that can be passed into transformerClass based on the configuration. Optional.
  • transport - Transport configuration to emit modified events. Required.

Behavior​

  • The configured transformerClass will be used to alter events before the emission.
  • Modified events will be passed into the configured transport for further processing.
  • In case of returning null, the event will be skipped.

EventTransformer interface​

public class CustomEventTransformer implements EventTransformer {
  @Override
  public void initialize(Map<String, String> properties) { ... }

  @Override
  public RunEvent transform(RunEvent event) { ... }

  @Override
  public DatasetEvent transform(DatasetEvent event) { .. }

  @Override
  public JobEvent transform(JobEvent event) { ... }
}

Examples​

transport:
  type: transform
  transformerClass: io.openlineage.CustomEventTransformer
  transformerProperties:
    key1: value1
    key2: value2
  transport:
    type: http
    url: http://example.com/api
    name: my_http

GcpLineage​

To use this transport in your project, you need to include io.openlineage:transports-gcplineage artifact in your build configuration. This is particularly important for environments like Spark, where this transport must be on the classpath for lineage events to be emitted correctly.

Configuration​

  • type - string, must be "gcplineage". Required.
  • endpoint - string, specifies the endpoint to which events are sent, default value is datalineage.googleapis.com:443. Optional.
  • projectId - string, the project quota identifier. If not provided, it is determined based on user credentials. Optional.
  • location - string, Dataplex location. Optional, default: "us".
  • credentialsFile - string, path to the Service Account credentials JSON file. Optional, if not provided Application Default Credentials are used
  • mode - enum that specifies the type of client used for publishing OpenLineage events to GCP Lineage service. Possible values: sync (synchronous) or async (asynchronous). Optional, default: async.

Behavior​

  • Events are serialized to JSON, included as part of a gRPC request, and then dispatched to the GCP Lineage service endpoint.
  • Depending on the mode chosen, requests are sent using either a synchronous or asynchronous client.

Examples​

transport:
  type: gcplineage
  projectId: your_gcp_project_id
  location: us
  mode: sync
  credentialsFile: path/to/credentials.json

Google Cloud Storage​

To use this transport in your project, you need to include io.openlineage:transports-gcs artifact in your build configuration. This is particularly important for environments like Spark, where this transport must be on the classpath for lineage events to be emitted correctly.

Configuration​

  • type - string, must be "gcs". Required.
  • projectId - string, the project quota identifier. Required.
  • credentialsFile - string, path to the Service Account credentials JSON file. Optional, if not provided Application Default Credentials are used
  • bucketName - string, the GCS bucket name. Required
  • fileNamePrefix - string, prefix for the event file names. Optional.

Behavior​

  • Events are serialized to JSON and stored in the specified GCS bucket.
  • Each event file is named based on its eventTime, converted to epoch milliseconds, with an optional prefix if configured.
  • Two constructors are available: one accepting both Storage and GcsTransportConfig and another solely accepting GcsTransportConfig.

Examples​

transport:
  type: gcs
  bucketName: my-gcs-bucket
  fileNamePrefix: /file/name/prefix/
  credentialsFile: path/to/credentials.json

DataZone Transport​

To use this transport in your project, you need to include io.openlineage:transports-datazone artifact in your build configuration. This is particularly important for environments like Spark, where this transport must be on the classpath for lineage events to be emitted correctly.

Configuration​

  • type - string, must be "amazon_datazone_api". Required.
  • domainId - string, specifies the DataZone / SageMaker Unified Studio domain id. The lineage events will be then sent to the following domain. Required.
  • region - string. When provided, the DataZone client will be configured to use this specific region. If endpointOverride is also provided, this value is not used. Optional, default: None (uses AWS SDK default region resolution).
  • endpointOverride - string, overrides the default HTTP endpoint for Amazon DataZone client. Default value will be set by AWS SDK to following endpoints based on the region. Optional, default: None

Behavior​

  • Events are serialized to JSON, and then dispatched to the DataZone / SageMaker Unified Studio endpoint.

Examples​

transport:
  type: amazon_datazone_api
  domainId: dzd-domain-id

S3​

To use this transport in your project, you need to include the following dependency in your build configuration. This is particularly important for environments like Spark, where this transport must be on the classpath for lineage events to be emitted correctly.

Maven​


<dependency>
    <groupId>io.openlineage</groupId>
    <artifactId>transports-s3</artifactId>
    <version>1.53.0</version>
</dependency>

Configuration​

  • type - string, must be "s3". Required.
  • endpoint - string, the endpoint for S3 compliant service like MinIO, Ceph, etc. Optional
  • bucketName - string, the S3 bucket name. Required
  • fileNamePrefix - string, prefix for the event file names. It is separated from the timestamp with underscore. It can include path and file name prefix. Optional.
Credentials​

To authenticate, the transport uses the default credentials provider chain. The possible authentication methods include:

  • Java system properties
  • Environment variables
  • Shared credentials config file (by default ~/.aws/config)
  • EC2 instance credentials (convenient in EMR and Glue)
  • and other

Refer to the documentation for details.

Behavior​

  • Events are serialized to JSON and stored in the specified S3 bucket.
  • Each event file is named based on its eventTime, converted to epoch milliseconds, with an optional prefix if configured.

Examples​

transport:
  type: s3
  endpoint: https://my-minio.example.com
  bucketName: events
  fileNamePrefix: my/service/events/event