OpenPipeline API - PUT a configuration
Updates an OpenPipeline configuration in your Dynatrace environment.
The request produces an application/json
payload.
PUT | SaaS | https://{your-environment-id}.apps.dynatrace.com/platform/openpipeline/v1/configurations/{id} |
Authentication
To execute this request, you need an OAuth2 client with openpipeline:configurations:write
permission.
To learn how to obtain and use it, see OAuth clients.
Parameters
Parameter | Type | Description | In | Required |
---|---|---|---|---|
id | string | Identifier of the configuration. | path | required |
body | Configuration | The updated configuration to apply. | body | required |
Request body objects
The Configuration
object
Full configuration containing ingest sources, pipelines and dynamic routing.
Element | Type | Description | Required |
---|---|---|---|
customBasePath | string | The base path for custom ingest endpoints. | required |
editable | boolean | Indicates if the user is allowed to edit this object based on permissions and builtin property. | optional |
endpoints | Endpoint | List of all ingest sources of the configuration. | required |
id | string | Identifier of the configuration. | required |
pipelines | Pipeline | List of all pipelines of the configuration. | required |
routing | Routing | Dynamic routing definition. | required |
version | string | The current version of the configuration. | required |
The EndpointDefinition
object
Definition of a single ingest source.
Element | Type | Description | Required |
---|---|---|---|
basePath | string | The base path of the ingest source. | required |
builtin | boolean | Indicates if the object is provided by Dynatrace or customer defined. | optional |
defaultBucket | string | The default bucket assigned to records for the ingest source. | optional |
displayName | string | Display name of the ingest source. | optional |
editable | boolean | Indicates if the user is allowed to edit this object based on permissions and builtin property. | optional |
enabled | boolean | Indicates if the object is active. | required |
processors | Endpoint | The pre-processing done in the ingest source. | optional |
routing | Routing | Routing strategy, either dynamic or static. | required |
segment | string | The segment of the ingest source, which is applied to the base path. Must be unique within a configuration. | required |
The EndpointProcessor
object
Groups all processors applicable for processing in the EndpointDefinition. Applicable processors are DqlProcessor, FieldsAddProcessor, FieldsRemoveProcessor and FieldsRenameProcessor.
The Routing
object
Routing strategy, either dynamic or static.
Element | Type | Description | Required |
---|---|---|---|
type | string | Defines the actual set of fields depending on the value. See one of the following objects:
| required |
The PipelineDefinition
object
Definition of a single pipeline, either 'default' or 'classic'.
Element | Type | Description | Required |
---|---|---|---|
builtin | boolean | Indicates if the object is provided by Dynatrace or customer defined. | optional |
dataExtraction | Data | Data extraction stage configuration of the pipeline. | optional |
displayName | string | Display name of the pipeline. | optional |
editable | boolean | Indicates if the user is allowed to edit this object based on permissions and builtin property. | optional |
enabled | boolean | Indicates if the object is active. | required |
id | string | Identifier of the pipeline. | required |
metricExtraction | Metric | Metric extraction stage configuration of the pipeline. | optional |
securityContext | Security | Security context stage configuration of the pipeline. | optional |
storage | Storage | Storage stage configuration of the pipeline. | optional |
type | string | Defines the actual set of fields depending on the value. See one of the following objects:
| required |
The DataExtractionStage
object
Data extraction stage configuration of the pipeline.
Element | Type | Description | Required |
---|---|---|---|
editable | boolean | Indicates if the user is allowed to edit this object based on permissions and builtin property. | optional |
processors | Data | List of processors. | required |
The DataExtractionStageProcessor
object
Groups all processors applicable for the DataExtractionStage. Applicable processors are DavisEventExtractionProcessor and BizeventExtractionProcessor.
The MetricExtractionStage
object
Metric extraction stage configuration of the pipeline.
Element | Type | Description | Required |
---|---|---|---|
editable | boolean | Indicates if the user is allowed to edit this object based on permissions and builtin property. | optional |
processors | Metric | List of processors. | required |
The MetricExtractionStageProcessor
object
Groups all processors applicable for the MetricExtractionStage. Applicable processors are CounterMetricExtractionProcessor and ValueMetricExtractionProcessor.
The SecurityContextStage
object
Security context stage configuration of the pipeline.
Element | Type | Description | Required |
---|---|---|---|
editable | boolean | Indicates if the user is allowed to edit this object based on permissions and builtin property. | optional |
processors | Security | List of processors. | required |
The SecurityContextStageProcessor
object
Groups all processors applicable for the SecurityContextStage. Applicable processor is SecurityContextProcessor.
The StorageStage
object
Storage stage configuration of the pipeline.
Element | Type | Description | Required |
---|---|---|---|
catchAllBucketName | string | Default bucket assigned to records which do not match any other storage processor. | required |
editable | boolean | Indicates if the user is allowed to edit this object based on permissions and builtin property. | optional |
processors | Storage | List of processors. | required |
The StorageStageProcessor
object
Groups all processors applicable for the StorageStage. Applicable processors are BucketAssignmentProcessor and NoStorageProcessor.
The RoutingTable
object
Dynamic routing definition.
Element | Type | Description | Required |
---|---|---|---|
catchAllPipeline | Routing | The default pipeline records are routed into if no dynamic routing entries apply. | required |
editable | boolean | Indicates if the user is allowed to edit this object based on permissions and builtin property. | optional |
entries | Routing | List of all dynamic routes. | required |
The RoutingTableEntryTarget
object
The default pipeline records are routed into if no dynamic routing entries apply.
Element | Type | Description | Required |
---|---|---|---|
editable | boolean | Indicates if the user is allowed to edit this object based on permissions and builtin property. | optional |
pipelineId | string | Identifier of the pipeline. | required |
The RoutingTableEntry
object
Dynamic routing entry.
Element | Type | Description | Required |
---|---|---|---|
builtin | boolean | Indicates if the object is provided by Dynatrace or customer defined. | optional |
editable | boolean | Indicates if the user is allowed to edit this object based on permissions and builtin property. | optional |
enabled | boolean | Indicates if the object is active. | required |
matcher | string | Matching condition to apply on incoming records. | required |
note | string | Unique note describing the dynamic route. | required |
pipelineId | string | Identifier of the pipeline the record is routed into. | required |
Request body JSON model
This is a model of the request body, showing the possible elements. It has to be adjusted for usage in an actual request.
{"id": "events","editable": false,"version": "1719220519649-ff2897a62cf849b0baa95e71fa4d5f1f","customBasePath": "/platform/ingest/custom/events","endpoints": [{"enabled": true,"builtin": false,"editable": false,"basePath": "/platform/ingest/custom/events","segment": "home","displayName": "Endpoint for home automation","defaultBucket": "home_automation_events","processors": [{"type": "fieldsRename","enabled": false,"editable": true,"id": "hostname-field-normalizer","description": "hostname field normalizer","matcher": "isNotNull(\"hostname\")","sampleData": "{\"hostname\": \"raspberry-pi 4\",\"ip\":\"10.0.0.123\"}","fields": [{"fromName": "hostname","toName": "host.name"},{"fromName": "ip","toName": "ip.address"}]},{"type": "fieldsAdd","enabled": false,"editable": true,"id": "add-source-field","description": "Add source field","matcher": "true","sampleData": "{\"hostname\": \"raspberry-pi 4\",\"ip\":\"10.0.0.123\"}","fields": [{"name": "source","value": "home-automation"}]}],"routing": {"type": "dynamic"}},{"enabled": true,"builtin": true,"editable": false,"basePath": "/platform/ingest/v1/events","segment": "","displayName": "Default API","defaultBucket": null,"processors": [],"routing": {"type": "dynamic"}}],"pipelines": [{"type": "default","enabled": true,"editable": false,"id": "home-automation","builtin": false,"displayName": "Home automation pipeline","storage": {"editable": false,"catchAllBucketName": "home_automation_events","processors": [{"type": "noStorage","id": "don-not-store-debug-events","description": "Do not store debugging events","enabled": true,"editable": false,"matcher": "severity==\"debug\"","sampleData": "{}"},{"type": "bucketAssignment","enabled": true,"editable": false,"id": "bucket-assignment-security-relevent-events","description": "Store security relevant events in dedicated bucket","matcher": "type==\"security\"","sampleData": "{}","bucketName": "home_automation_security_events"}]},"securityContext": {"editable": false,"processors": [{"type": "securityContext","id": "security-context","description": "Mark security context for supervisors","enabled": true,"editable": false,"matcher": "type==\"security\"","sampleData": "{}","value": {"type": "constant","constant": "supervisors"}}]},"metricExtraction": {"editable": false,"processors": [{"type": "counterMetric","id": "click-counter-metric","description": "Counts the clicks on a button","enabled": true,"editable": true,"matcher": "device.type==\"button\"","sampleData": "{}","metricKey": "events.home.button.click","dimensions": ["device.name","device.location"]},{"type": "valueMetric","id": "temperature-value-metric","description": "description","enabled": true,"editable": true,"matcher": "device.type==\"temperature-sensor\"","sampleData": "{}","metricKey": "events.home.temperature","dimensions": ["device.name","device.location"],"field": "temperature"}]},"dataExtraction": {"editable": false,"processors": []},"processing": {"editable": false,"processors": []}},{"type": "default","enabled": true,"editable": false,"id": "default","builtin": true,"displayName": "events","storage": {"editable": false,"catchAllBucketName": "default_events","processors": []},"securityContext": {"editable": false,"processors": []},"metricExtraction": {"editable": false,"processors": []},"dataExtraction": {"editable": false,"processors": []},"processing": {"editable": false,"processors": []}}],"routing": {"editable": false,"catchAllPipeline": {"editable": false,"pipelineId": "default"},"entries": [{"enabled": true,"editable": false,"builtin": false,"pipelineId": "home-automation","matcher": "source==\"home-automation\"","note": "Route all home automation events into dedicated pipeline"}]}}
Response
Response codes
Code | Type | Description |
---|---|---|
202 | - | Configuration change was accepted. |
409 | Error | Version conflict. |
413 | Error | Max Payload size of 10 MiB exceeded. |
4XX | Error | Client-side error. |
5XX | Error | Server-side error. |
JSON models
The ConstantValueAssignment
object
Assign a constant value.
Element | Type | Description |
---|---|---|
constant | string | The constant value to assign. |
The FieldValueAssignment
object
Assign a value extracted from a field.
Element | Type | Description |
---|---|---|
field | string | The field on the record to extract the value for assignment. |
The StaticRouting
object
Records are statically routed to the defined pipeline.
Element | Type | Description |
---|---|---|
pipelineId | string | Identifier of the pipeline. |
The DynamicRouting
object
Records are routed via the dynamic routes.
The ClassicPipelineDefinition
object
Definition of a classic pipeline which are configured via settings 2.0. This only applies to the logs and bizevents configuration.
Element | Type | Description |
---|---|---|
processing | Classic | Processing stage configuration of the pipeline. |
settingsSchema | string | The settings-schema identifier related to the processing of the classic pipeline. |
The ClassicProcessingStage
object
Processing stage configuration of the pipeline.
Element | Type | Description |
---|---|---|
editable | boolean | Indicates if the user is allowed to edit this object based on permissions and builtin property. |
processors | Classic | List of processors. |
The ClassicProcessingStageProcessor
object
Groups all processors applicable for the ClassicProcessingStage. Applicable processor is SxqlProcessor.
The SxqlProcessor
object
Processor to apply a SXQL script.
Element | Type | Description |
---|---|---|
description | string | Name or description of the processor. |
editable | boolean | Indicates if the user is allowed to edit this object based on permissions and builtin property. |
enabled | boolean | Indicates if the object is active. |
id | string | Identifier of the processor. Must be unique within a stage. |
matcher | string | Matching condition to apply on incoming records. |
sampleData | string | Sample data related to the processor for documentation or testing. |
sxqlScript | string | The SXQL script to apply on the record. |
The DefaultPipelineDefinition
object
Definition of a single default pipeline.
Element | Type | Description |
---|---|---|
processing | Processing | Processing stage configuration of the pipeline. |
The ProcessingStage
object
Processing stage configuration of the pipeline.
Element | Type | Description |
---|---|---|
editable | boolean | Indicates if the user is allowed to edit this object based on permissions and builtin property. |
processors | Processing | List of processors. |
The ProcessingStageProcessor
object
Groups all processors applicable for the ProcessingStage. Applicable processors are DqlProcessor, FieldsAddProcessor, FieldsRemoveProcessor and FieldsRenameProcessor.
The BizeventExtractionProcessor
object
Processor to extract a bizevent. This processor can only be applied to the logs configuration.
Element | Type | Description |
---|---|---|
description | string | Name or description of the processor. |
editable | boolean | Indicates if the user is allowed to edit this object based on permissions and builtin property. |
enabled | boolean | Indicates if the object is active. |
eventProvider | Value | Strategy to assign a value. |
eventType | Value | Strategy to assign a value. |
fieldExtraction | Bizevent | Definition of the field extraction. |
id | string | Identifier of the processor. Must be unique within a stage. |
matcher | string | Matching condition to apply on incoming records. |
sampleData | string | Sample data related to the processor for documentation or testing. |
The ValueAssignment
object
Strategy to assign a value.
Element | Type | Description |
---|---|---|
type | string | Defines the actual set of fields depending on the value. See one of the following objects:
|
The BizeventFieldExtraction
object
Definition of the field extraction.
Element | Type | Description |
---|---|---|
fields | string[] | Fields to include/exclude in the extracted bizevent. |
semantic | string | Defines how the fields of the source record should be extracted into the bizevent. INCLUDE: Only the specified fields are extracted. INCLUDE_ALL: All fields are extracted. EXCLUDE: All fields except the specified fields are extracted.
|
The DavisEventExtractionProcessor
object
Processor to extract a davis event.
Element | Type | Description |
---|---|---|
description | string | Name or description of the processor. |
editable | boolean | Indicates if the user is allowed to edit this object based on permissions and builtin property. |
enabled | boolean | Indicates if the object is active. |
id | string | Identifier of the processor. Must be unique within a stage. |
matcher | string | Matching condition to apply on incoming records. |
properties | Davis | List of properties for the extracted davis event. |
sampleData | string | Sample data related to the processor for documentation or testing. |
The DavisEventProperty
object
List of properties for the extracted davis event.
Element | Type | Description |
---|---|---|
key | string | The key to set on the davis event. |
value | string | The value assigned to the key. |
The DqlProcessor
object
Processor to apply a DQL script.
Element | Type | Description |
---|---|---|
description | string | Name or description of the processor. |
dqlScript | string | The DQL script to apply on the record. |
editable | boolean | Indicates if the user is allowed to edit this object based on permissions and builtin property. |
enabled | boolean | Indicates if the object is active. |
id | string | Identifier of the processor. Must be unique within a stage. |
matcher | string | Matching condition to apply on incoming records. |
sampleData | string | Sample data related to the processor for documentation or testing. |
The FieldsAddProcessor
object
Processor to add fields.
Element | Type | Description |
---|---|---|
description | string | Name or description of the processor. |
editable | boolean | Indicates if the user is allowed to edit this object based on permissions and builtin property. |
enabled | boolean | Indicates if the object is active. |
fields | Fields | List of fields to add to the record. |
id | string | Identifier of the processor. Must be unique within a stage. |
matcher | string | Matching condition to apply on incoming records. |
sampleData | string | Sample data related to the processor for documentation or testing. |
The FieldsAddItem
object
List of fields to add to the record.
Element | Type | Description |
---|---|---|
name | string | Name of the field. |
value | string | Value to assign to the field. |
The FieldsRemoveProcessor
object
Processor to remove fields.
Element | Type | Description |
---|---|---|
description | string | Name or description of the processor. |
editable | boolean | Indicates if the user is allowed to edit this object based on permissions and builtin property. |
enabled | boolean | Indicates if the object is active. |
fields | string[] | List of fields to remove from the record. |
id | string | Identifier of the processor. Must be unique within a stage. |
matcher | string | Matching condition to apply on incoming records. |
sampleData | string | Sample data related to the processor for documentation or testing. |
The FieldsRenameProcessor
object
Processor to rename fields.
Element | Type | Description |
---|---|---|
description | string | Name or description of the processor. |
editable | boolean | Indicates if the user is allowed to edit this object based on permissions and builtin property. |
enabled | boolean | Indicates if the object is active. |
fields | Fields | List of fields to rename on the record. |
id | string | Identifier of the processor. Must be unique within a stage. |
matcher | string | Matching condition to apply on incoming records. |
sampleData | string | Sample data related to the processor for documentation or testing. |
The FieldsRenameItem
object
List of fields to rename on the record.
Element | Type | Description |
---|---|---|
fromName | string | The field to rename. |
toName | string | The new field name. |
The NoStorageProcessor
object
Processor to skip storage assignment.
Element | Type | Description |
---|---|---|
description | string | Name or description of the processor. |
editable | boolean | Indicates if the user is allowed to edit this object based on permissions and builtin property. |
enabled | boolean | Indicates if the object is active. |
id | string | Identifier of the processor. Must be unique within a stage. |
matcher | string | Matching condition to apply on incoming records. |
sampleData | string | Sample data related to the processor for documentation or testing. |
The BucketAssignmentProcessor
object
Processor to assign a bucket.
Element | Type | Description |
---|---|---|
bucketName | string | Bucket that is assigned when the record is matched. |
description | string | Name or description of the processor. |
editable | boolean | Indicates if the user is allowed to edit this object based on permissions and builtin property. |
enabled | boolean | Indicates if the object is active. |
id | string | Identifier of the processor. Must be unique within a stage. |
matcher | string | Matching condition to apply on incoming records. |
sampleData | string | Sample data related to the processor for documentation or testing. |
The SecurityContextProcessor
object
Processor to set the security context field.
Element | Type | Description |
---|---|---|
description | string | Name or description of the processor. |
editable | boolean | Indicates if the user is allowed to edit this object based on permissions and builtin property. |
enabled | boolean | Indicates if the object is active. |
id | string | Identifier of the processor. Must be unique within a stage. |
matcher | string | Matching condition to apply on incoming records. |
sampleData | string | Sample data related to the processor for documentation or testing. |
value | Value | Strategy to assign a value. |
The ValueAssignment
object
Strategy to assign a value.
Element | Type | Description |
---|---|---|
type | string | Defines the actual set of fields depending on the value. See one of the following objects:
|
The CounterMetricExtractionProcessor
object
Processor to write the occurrences as a metric.
Element | Type | Description |
---|---|---|
description | string | Name or description of the processor. |
dimensions | string[] | List of dimensions to add to the metric. |
editable | boolean | Indicates if the user is allowed to edit this object based on permissions and builtin property. |
enabled | boolean | Indicates if the object is active. |
id | string | Identifier of the processor. Must be unique within a stage. |
matcher | string | Matching condition to apply on incoming records. |
metricKey | string | The key of the metric to write. |
sampleData | string | Sample data related to the processor for documentation or testing. |
The ValueMetricExtractionProcessor
object
Processor to extract a value from a field as a metric.
Element | Type | Description |
---|---|---|
description | string | Name or description of the processor. |
dimensions | string[] | List of dimensions to add to the metric. |
editable | boolean | Indicates if the user is allowed to edit this object based on permissions and builtin property. |
enabled | boolean | Indicates if the object is active. |
field | string | The field to extract the value for the metric. |
id | string | Identifier of the processor. Must be unique within a stage. |
matcher | string | Matching condition to apply on incoming records. |
metricKey | string | The key of the metric to write. |
sampleData | string | Sample data related to the processor for documentation or testing. |
The ErrorResponseEnvelope
object
Encloses the encountered error.
Element | Type | Description |
---|---|---|
error | Error | Basic information of the encountered error. |
The ErrorResponse
object
Basic information of the encountered error.
Element | Type | Description |
---|---|---|
code | integer | The returned HTTP status code. |
details | Error | Detailed information of the error. |
message | string | Description of the encountered error. |
The ErrorResponseDetails
object
Detailed information of the error.
Element | Type | Description |
---|---|---|
type | string | Defines the actual set of fields depending on the value. See one of the following objects:
|
The ConstraintViolationDetails
object
List of encountered constraint violations.
Element | Type | Description |
---|---|---|
constraintViolations | Constraint | List of encountered constraint violations. |
The ConstraintViolation
object
Information about a single constraint violation.
Element | Type | Description |
---|---|---|
message | string | Description of the constraint violation. |