openapi: 3.0.3 info: title: Feldera Input Connectors Metrics & Debugging API description: "\nWith Feldera, users create data pipelines out of SQL programs.\nA SQL program comprises tables and views, and includes as well the definition of\ninput and output connectors for each respectively. A connector defines a data\nsource or data sink to feed input data into tables or receive output data\ncomputed by the views respectively.\n\n## Pipeline\n\nThe API is centered around the **pipeline**, which most importantly consists\nout of the SQL program, but also has accompanying metadata and configuration parameters\n(e.g., compilation profile, number of workers, etc.).\n\n* A pipeline is identified and referred to by its user-provided unique name.\n* The pipeline program is asynchronously compiled when the pipeline is first created or\n when its program is subsequently updated.\n* Pipeline deployment start is only able to proceed to provisioning once the program is successfully\n compiled.\n* A pipeline cannot be updated while it is deployed.\n\n## Concurrency\n\nEach pipeline has a version, which is incremented each time its core fields are updated.\nThe version is monotonically increasing. There is additionally a program version which covers\nonly the program-related core fields, and is used by the compiler to discern when to recompile.\n\n## Client request handling\n\n### Request outcome expectations\n\nThe outcome of a request is that it either fails (e.g., DNS lookup failed) without any response\n(no status code nor body), or it succeeds and gets back a response status code and body.\n\nIn case of a response, usually it is the Feldera endpoint that generated it:\n- If it is success (2xx), it will return whichever body belongs to the success response.\n- Otherwise, if it is an error (4xx, 5xx), it will return a Feldera error response JSON body\n which will have an application-level `error_code`.\n\nHowever, there are two notable exceptions when the response is not generated by the Feldera\nendpoint:\n- If the HTTP server, to which the endpoint belongs, encountered an issue, it might return\n 4xx (e.g., for an unknown endpoint) or 5xx error codes by itself (e.g., when it is initializing).\n- If the Feldera API server is behind a (reverse) proxy, the proxy can return error codes by itself,\n for example BAD GATEWAY (502) or GATEWAY TIMEOUT (504).\n\nAs such, it is not guaranteed that the (4xx, 5xx) will have a Feldera error response JSON body\nin these latter cases.\n\n### Error handling and retrying\n\nThe error type returned by the client should distinguish between the error responses generated\nby Feldera endpoints themselves (which have a Feldera error response body) and those that are\ngenerated by other sources.\n\nIn order for a client operation (e.g., `pipeline.resume()`) to be robust (i.e., not fail due to\na single HTTP request not succeeding) the client should use a retry mechanism if the operation\nis idempotent. The retry mechanism must however have a time limit, after which it times out.\nThis guarantees that the client operation is eventually responsive, which enables the script\nit is a part of to not hang indefinitely on Feldera operations and instead be able to decide\nby itself whether and how to proceed. If no response is returned, the mechanism should generally\nretry. When a response is returned, the decision whether to retry can generally depend on the status\ncode: especially the status codes 408, 502, 503 and 504 should be considered as transient errors.\nFiner grained retry decisions should be made by taking into account the application-level\n`error_code` if the response body was indeed a Feldera error response body.\n\n## Feldera client errors (4xx)\n\n_Client behavior:_ clients should generally return with an error when they get back a 4xx status\ncode, as it usually means the request will likely not succeed even if it is sent again. Certain\nrequests might make use of a timed retry mechanism when the client error is transient without\nrequiring any user intervention to overcome, for instance a transaction already being in progress\nleading to a temporary CONFLICT (409) error.\n\n- **BAD REQUEST (400)**: invalid user request (general).\n - _Example:_ the new pipeline name `example1@~` contains invalid characters.\n\n- **UNAUTHORIZED (401)**: the user is not authorized to issue the request.\n - _Example:_ an invalid API key is provided.\n\n- **NOT FOUND (404)**: a resource required to exist in order to process the request was not found.\n - _Example:_ a pipeline named `example` does not exist when trying to update it.\n\n- **CONFLICT (409)**: there is a conflict between the request and a relevant resource.\n - _Example:_ a pipeline named `example` already exists.\n - _Example:_ another transaction is already in process.\n\n## Feldera server errors (5xx)\n\n- **INTERNAL SERVER ERROR (500)**: the server is unexpectedly unable to process the request\n (general).\n - _Example:_ unable to reach the database.\n - _Client behavior:_ immediately return with an error.\n\n- **NOT IMPLEMENTED (501)**: the server does not implement functionality required to process the\n request.\n - _Example:_ making a request to an enterprise-only endpoint in the OSS edition.\n - _Client behavior:_ immediately return with an error.\n\n- **SERVICE UNAVAILABLE (503)**: the server is not (yet) able to process the request.\n - _Example:_ pausing a pipeline which is still provisioning.\n - _Client behavior:_ depending on the type of request, client may use a timed retry mechanism.\n\n## Feldera error response body\n\nWhen the Feldera API returns an HTTP error status code (4xx, 5xx), the body will contain the\nfollowing JSON object:\n\n```json\n{\n \"message\": \"Human-readable explanation.\",\n \"error_code\": \"CodeSpecifyingError\",\n \"details\": {\n\n }\n}\n```\n\nIt contains the following fields:\n- **message (string)**: human-readable explanation of the error that occurred and potentially\n hinting what can be done about it.\n- **error_code (string)**: application-level code about the error that occurred, written in CamelCase.\n For example: `UnknownPipelineName`, `DuplicateName`, `PauseWhileNotProvisioned`, ... .\n- **details (object)**: JSON object corresponding to the `error_code` with fields that provide\n details relevant to it. For example: if a name is unknown, a field with the unknown name in\n question.\n" contact: name: Feldera Team email: dev@feldera.com license: name: MIT OR Apache-2.0 version: 0.323.0 tags: - name: Metrics & Debugging paths: /v0/metrics: get: tags: - Metrics & Debugging summary: List All Metrics description: 'Retrieve the metrics of all running pipelines belonging to this tenant. The metrics are collected by making individual HTTP requests to `/metrics` endpoint of each pipeline, of which only successful responses are included in the returned list.' operationId: get_metrics responses: '200': description: Metrics of all running pipelines belonging to this tenant in Prometheus format content: text/plain: schema: type: string format: binary security: - JSON web token (JWT) or API key: [] /v0/pipelines/{pipeline_name}/circuit_json_profile: get: tags: - Metrics & Debugging summary: Performance Profile JSON description: Retrieve the circuit performance profile in JSON format of a running or paused pipeline. operationId: get_pipeline_circuit_json_profile parameters: - name: pipeline_name in: path description: Unique pipeline name required: true schema: type: string responses: '200': description: Circuit performance profile in JSON format content: application/json: schema: type: object '404': description: Pipeline with that name does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: Unknown pipeline name 'non-existent-pipeline' error_code: UnknownPipelineName details: pipeline_name: non-existent-pipeline '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Disconnected during response: value: message: 'Error sending HTTP request to pipeline: the pipeline disconnected while it was processing this HTTP request. This could be because the pipeline either (a) encountered a fatal error or panic, (b) was stopped, or (c) experienced network issues -- retrying might help in the last case. Alternatively, check the pipeline logs. Failed request: /pause pipeline-id=N/A pipeline-name="my_pipeline"' error_code: PipelineInteractionUnreachable details: pipeline_name: my_pipeline request: /pause error: the pipeline disconnected while it was processing this HTTP request. This could be because the pipeline either (a) encountered a fatal error or panic, (b) was stopped, or (c) experienced network issues -- retrying might help in the last case. Alternatively, check the pipeline logs. Pipeline is currently unavailable: value: message: 'Error sending HTTP request to pipeline: deployment status is currently ''unavailable'' -- wait for it to become ''running'' or ''paused'' again Failed request: /pause pipeline-id=N/A pipeline-name="my_pipeline"' error_code: PipelineInteractionUnreachable details: pipeline_name: my_pipeline request: /pause error: deployment status is currently 'unavailable' -- wait for it to become 'running' or 'paused' again Pipeline is not deployed: value: message: Unable to interact with pipeline because the deployment status (stopped) indicates it is not (yet) fully provisioned pipeline-id=N/A pipeline-name="my_pipeline" error_code: PipelineInteractionNotDeployed details: pipeline_name: my_pipeline status: Stopped desired_status: Provisioned Response timeout: value: message: 'Error sending HTTP request to pipeline: timeout (10s) was reached: this means the pipeline took too long to respond -- this can simply be because the request was too difficult to process in time, or other reasons (e.g., deadlock): the pipeline logs might contain additional information (original send request error: Timeout while waiting for response) Failed request: /pause pipeline-id=N/A pipeline-name="my_pipeline"' error_code: PipelineInteractionUnreachable details: pipeline_name: my_pipeline request: /pause error: 'timeout (10s) was reached: this means the pipeline took too long to respond -- this can simply be because the request was too difficult to process in time, or other reasons (e.g., deadlock): the pipeline logs might contain additional information (original send request error: Timeout while waiting for response)' security: - JSON web token (JWT) or API key: [] /v0/pipelines/{pipeline_name}/circuit_profile: get: tags: - Metrics & Debugging summary: Get Performance Profile description: Retrieve the circuit performance profile of a running or paused pipeline. operationId: get_pipeline_circuit_profile parameters: - name: pipeline_name in: path description: Unique pipeline name required: true schema: type: string responses: '200': description: Circuit performance profile content: application/zip: schema: type: object '404': description: Pipeline with that name does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: Unknown pipeline name 'non-existent-pipeline' error_code: UnknownPipelineName details: pipeline_name: non-existent-pipeline '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Disconnected during response: value: message: 'Error sending HTTP request to pipeline: the pipeline disconnected while it was processing this HTTP request. This could be because the pipeline either (a) encountered a fatal error or panic, (b) was stopped, or (c) experienced network issues -- retrying might help in the last case. Alternatively, check the pipeline logs. Failed request: /pause pipeline-id=N/A pipeline-name="my_pipeline"' error_code: PipelineInteractionUnreachable details: pipeline_name: my_pipeline request: /pause error: the pipeline disconnected while it was processing this HTTP request. This could be because the pipeline either (a) encountered a fatal error or panic, (b) was stopped, or (c) experienced network issues -- retrying might help in the last case. Alternatively, check the pipeline logs. Pipeline is currently unavailable: value: message: 'Error sending HTTP request to pipeline: deployment status is currently ''unavailable'' -- wait for it to become ''running'' or ''paused'' again Failed request: /pause pipeline-id=N/A pipeline-name="my_pipeline"' error_code: PipelineInteractionUnreachable details: pipeline_name: my_pipeline request: /pause error: deployment status is currently 'unavailable' -- wait for it to become 'running' or 'paused' again Pipeline is not deployed: value: message: Unable to interact with pipeline because the deployment status (stopped) indicates it is not (yet) fully provisioned pipeline-id=N/A pipeline-name="my_pipeline" error_code: PipelineInteractionNotDeployed details: pipeline_name: my_pipeline status: Stopped desired_status: Provisioned Response timeout: value: message: 'Error sending HTTP request to pipeline: timeout (10s) was reached: this means the pipeline took too long to respond -- this can simply be because the request was too difficult to process in time, or other reasons (e.g., deadlock): the pipeline logs might contain additional information (original send request error: Timeout while waiting for response) Failed request: /pause pipeline-id=N/A pipeline-name="my_pipeline"' error_code: PipelineInteractionUnreachable details: pipeline_name: my_pipeline request: /pause error: 'timeout (10s) was reached: this means the pipeline took too long to respond -- this can simply be because the request was too difficult to process in time, or other reasons (e.g., deadlock): the pipeline logs might contain additional information (original send request error: Timeout while waiting for response)' security: - JSON web token (JWT) or API key: [] /v0/pipelines/{pipeline_name}/clock/advance: post: tags: - Metrics & Debugging summary: Advance Clock description: 'Moves `NOW()` forward by a specified amount. Returns the current clock time of the circuit. Requires `dev_tweaks.now_http_driven = true` on the pipeline. Forward-only: `delta_ms` is `u64`, so negative bodies are rejected at JSON parse time. `delta_ms = null` or omitted advances by one `clock_resolution`. Non-zero values round up to the next `clock_resolution` boundary, so a sub-resolution delta still moves the clock by one full tick. The returned `now_ms` is the value the worker will emit on its next pipeline step; queries against materialized views may observe the previous `NOW()` until that step completes. Callers that need read-after-write semantics should poll the view.' operationId: clock_advance parameters: - name: pipeline_name in: path description: Unique pipeline name required: true schema: type: string requestBody: description: 'Milliseconds to add to NOW(); zero reads the current value, null/omitted: advance by one clock_resolution.' content: application/json: schema: $ref: '#/components/schemas/ClockAdvanceRequest' required: true responses: '200': description: Clock advanced successfully; body contains the new NOW(). content: application/json: schema: $ref: '#/components/schemas/ClockAdvanceResponse' '400': description: Clock not in http-driven mode, or malformed body. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Pipeline is not running. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - JSON web token (JWT) or API key: [] /v0/pipelines/{pipeline_name}/dataflow_graph: get: tags: - Metrics & Debugging summary: Get Dataflow Graph description: 'Retrieve the dataflow graph of a pipeline. The dataflow graph is generated during SQL compilation and shows the structure of the compiled SQL program including the Calcite plan and MIR nodes.' operationId: get_pipeline_dataflow_graph parameters: - name: pipeline_name in: path description: Unique pipeline name required: true schema: type: string responses: '200': description: Dataflow graph retrieved successfully content: application/json: schema: type: object '404': description: Pipeline with that name does not exist or dataflow graph is not available content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: Unknown pipeline name 'non-existent-pipeline' error_code: UnknownPipelineName details: pipeline_name: non-existent-pipeline '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - JSON web token (JWT) or API key: [] /v0/pipelines/{pipeline_name}/events: get: tags: - Metrics & Debugging summary: List Pipeline Events description: 'Retrieve monitoring events in reverse chronological order. Pipeline health is monitored regularly every several seconds. Not every monitoring action results in a pipeline monitor event being constructed and inserted into the database. This happens if: - Any status changed - Only the status details changed, and it has been 10s since the last event - Nothing has changed for more than 10 minutes This endpoint returns the most recent persisted events, up to by default approximately 720.' operationId: list_pipeline_events parameters: - name: pipeline_name in: path description: Unique pipeline name required: true schema: type: string - name: selector in: query description: 'The `selector` parameter limits which fields are returned. Limiting which fields is particularly handy for instance when frequently monitoring over low bandwidth connections while being only interested in status.' required: false schema: $ref: '#/components/schemas/PipelineMonitorEventFieldSelector' responses: '200': description: '' content: application/json: schema: type: array items: $ref: '#/components/schemas/PipelineMonitorEventSelectedInfo' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - JSON web token (JWT) or API key: [] /v0/pipelines/{pipeline_name}/events/{event_id}: get: tags: - Metrics & Debugging summary: Get Pipeline Event description: 'Get a specific pipeline monitor event. The identifiers of the events can be retrieved via `GET /v0/pipelines//events`. The most recent approximately 720 (default) events are retained. This endpoint can return a 404 for an event that no longer exists due to a cleanup.' operationId: get_pipeline_event parameters: - name: event_id in: path description: Pipeline monitor event identifier or `latest` required: true schema: type: string - name: pipeline_name in: path description: Unique pipeline name required: true schema: type: string - name: selector in: query description: 'The `selector` parameter limits which fields are returned. Limiting which fields is particularly handy for instance when frequently monitoring over low bandwidth connections while being only interested in status.' required: false schema: $ref: '#/components/schemas/PipelineMonitorEventFieldSelector' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/PipelineMonitorEventSelectedInfo' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - JSON web token (JWT) or API key: [] /v0/pipelines/{pipeline_name}/heap_profile: get: tags: - Metrics & Debugging summary: Get Heap Profile description: Retrieve the heap profile of a running or paused pipeline. operationId: get_pipeline_heap_profile parameters: - name: pipeline_name in: path description: Unique pipeline name required: true schema: type: string responses: '200': description: Heap usage profile as a gzipped protobuf that can be inspected by the pprof tool content: application/protobuf: schema: type: string format: binary '400': description: Getting a heap profile is not supported on this platform content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Pipeline with that name does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: Unknown pipeline name 'non-existent-pipeline' error_code: UnknownPipelineName details: pipeline_name: non-existent-pipeline '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Disconnected during response: value: message: 'Error sending HTTP request to pipeline: the pipeline disconnected while it was processing this HTTP request. This could be because the pipeline either (a) encountered a fatal error or panic, (b) was stopped, or (c) experienced network issues -- retrying might help in the last case. Alternatively, check the pipeline logs. Failed request: /pause pipeline-id=N/A pipeline-name="my_pipeline"' error_code: PipelineInteractionUnreachable details: pipeline_name: my_pipeline request: /pause error: the pipeline disconnected while it was processing this HTTP request. This could be because the pipeline either (a) encountered a fatal error or panic, (b) was stopped, or (c) experienced network issues -- retrying might help in the last case. Alternatively, check the pipeline logs. Pipeline is currently unavailable: value: message: 'Error sending HTTP request to pipeline: deployment status is currently ''unavailable'' -- wait for it to become ''running'' or ''paused'' again Failed request: /pause pipeline-id=N/A pipeline-name="my_pipeline"' error_code: PipelineInteractionUnreachable details: pipeline_name: my_pipeline request: /pause error: deployment status is currently 'unavailable' -- wait for it to become 'running' or 'paused' again Pipeline is not deployed: value: message: Unable to interact with pipeline because the deployment status (stopped) indicates it is not (yet) fully provisioned pipeline-id=N/A pipeline-name="my_pipeline" error_code: PipelineInteractionNotDeployed details: pipeline_name: my_pipeline status: Stopped desired_status: Provisioned Response timeout: value: message: 'Error sending HTTP request to pipeline: timeout (10s) was reached: this means the pipeline took too long to respond -- this can simply be because the request was too difficult to process in time, or other reasons (e.g., deadlock): the pipeline logs might contain additional information (original send request error: Timeout while waiting for response) Failed request: /pause pipeline-id=N/A pipeline-name="my_pipeline"' error_code: PipelineInteractionUnreachable details: pipeline_name: my_pipeline request: /pause error: 'timeout (10s) was reached: this means the pipeline took too long to respond -- this can simply be because the request was too difficult to process in time, or other reasons (e.g., deadlock): the pipeline logs might contain additional information (original send request error: Timeout while waiting for response)' security: - JSON web token (JWT) or API key: [] /v0/pipelines/{pipeline_name}/logs: get: tags: - Metrics & Debugging summary: Stream Pipeline Logs description: 'Retrieve logs of a pipeline as a stream. The logs stream catches up to the extent of the internally configured per-pipeline circular logs buffer (limited to a certain byte size and number of lines, whichever is reached first). After the catch-up, new lines are pushed whenever they become available. It is possible for the logs stream to end prematurely due to the API server temporarily losing connection to the runner. In this case, it is needed to issue again a new request to this endpoint. The logs stream will end when the pipeline is deleted, or if the runner restarts. Note that in both cases the logs will be cleared.' operationId: get_pipeline_logs parameters: - name: pipeline_name in: path description: Unique pipeline name required: true schema: type: string responses: '200': description: Pipeline logs retrieved successfully content: text/plain: schema: type: string format: binary '404': description: Pipeline with that name does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: Unknown pipeline name 'non-existent-pipeline' error_code: UnknownPipelineName details: pipeline_name: non-existent-pipeline '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Runner response timeout: value: message: 'Unable to reach pipeline runner to interact due to: timeout (10s) was reached: this means the pipeline took too long to respond -- this can simply be because the request was too difficult to process in time, or other reasons (e.g., deadlock): the pipeline logs might contain additional information (original send request error: Timeout while waiting for response)' error_code: RunnerInteractionUnreachable details: error: 'timeout (10s) was reached: this means the pipeline took too long to respond -- this can simply be because the request was too difficult to process in time, or other reasons (e.g., deadlock): the pipeline logs might contain additional information (original send request error: Timeout while waiting for response)' security: - JSON web token (JWT) or API key: [] /v0/pipelines/{pipeline_name}/metrics: get: tags: - Metrics & Debugging summary: Get Pipeline Metrics description: Retrieve the metrics of a running or paused pipeline. operationId: get_pipeline_metrics parameters: - name: pipeline_name in: path description: Unique pipeline name required: true schema: type: string - name: format in: query required: false schema: $ref: '#/components/schemas/MetricsFormat' responses: '200': description: Pipeline circuit metrics retrieved successfully content: application/octet-stream: schema: type: string format: binary '404': description: Pipeline with that name does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: Unknown pipeline name 'non-existent-pipeline' error_code: UnknownPipelineName details: pipeline_name: non-existent-pipeline '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Disconnected during response: value: message: 'Error sending HTTP request to pipeline: the pipeline disconnected while it was processing this HTTP request. This could be because the pipeline either (a) encountered a fatal error or panic, (b) was stopped, or (c) experienced network issues -- retrying might help in the last case. Alternatively, check the pipeline logs. Failed request: /pause pipeline-id=N/A pipeline-name="my_pipeline"' error_code: PipelineInteractionUnreachable details: pipeline_name: my_pipeline request: /pause error: the pipeline disconnected while it was processing this HTTP request. This could be because the pipeline either (a) encountered a fatal error or panic, (b) was stopped, or (c) experienced network issues -- retrying might help in the last case. Alternatively, check the pipeline logs. Pipeline is currently unavailable: value: message: 'Error sending HTTP request to pipeline: deployment status is currently ''unavailable'' -- wait for it to become ''running'' or ''paused'' again Failed request: /pause pipeline-id=N/A pipeline-name="my_pipeline"' error_code: PipelineInteractionUnreachable details: pipeline_name: my_pipeline request: /pause error: deployment status is currently 'unavailable' -- wait for it to become 'running' or 'paused' again Pipeline is not deployed: value: message: Unable to interact with pipeline because the deployment status (stopped) indicates it is not (yet) fully provisioned pipeline-id=N/A pipeline-name="my_pipeline" error_code: PipelineInteractionNotDeployed details: pipeline_name: my_pipeline status: Stopped desired_status: Provisioned Response timeout: value: message: 'Error sending HTTP request to pipeline: timeout (10s) was reached: this means the pipeline took too long to respond -- this can simply be because the request was too difficult to process in time, or other reasons (e.g., deadlock): the pipeline logs might contain additional information (original send request error: Timeout while waiting for response) Failed request: /pause pipeline-id=N/A pipeline-name="my_pipeline"' error_code: PipelineInteractionUnreachable details: pipeline_name: my_pipeline request: /pause error: 'timeout (10s) was reached: this means the pipeline took too long to respond -- this can simply be because the request was too difficult to process in time, or other reasons (e.g., deadlock): the pipeline logs might contain additional information (original send request error: Timeout while waiting for response)' security: - JSON web token (JWT) or API key: [] /v0/pipelines/{pipeline_name}/samply_profile: get: tags: - Metrics & Debugging summary: Get Samply Profile description: 'Retrieve the last samply profile of a pipeline, regardless of whether profiling is currently in progress. If ?latest parameter is specified and Samply profile collection is in progress, returns HTTP 307 with Retry-After header.' operationId: get_pipeline_samply_profile parameters: - name: pipeline_name in: path description: Unique pipeline name required: true schema: type: string - name: ordinal in: query description: In a multihost pipeline, the ordinal of the pipeline to sample. required: false schema: type: integer minimum: 0 - name: latest in: query description: 'If true, returns 204 redirect with Retry-After header if profile collection is in progress. If false or not provided, returns the last collected profile.' required: false schema: type: boolean responses: '200': description: 'Samply profile as a gzip containing the profile that can be inspected by the samply tool. Note: may return 204 No Content with Retry-After header if latest=true and profiling is in progress.' content: application/gzip: schema: type: string format: binary '400': description: No samply profile exists for the pipeline, create one by calling `POST /pipelines/{pipeline_name}/samply_profile?duration_secs=30` content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Pipeline with that name does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: Unknown pipeline name 'non-existent-pipeline' error_code: UnknownPipelineName details: pipeline_name: non-existent-pipeline '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Disconnected during response: value: message: 'Error sending HTTP request to pipeline: the pipeline disconnected while it was processing this HTTP request. This could be because the pipeline either (a) encountered a fatal error or panic, (b) was stopped, or (c) experienced network issues -- retrying might help in the last case. Alternatively, check the pipeline logs. Failed request: /pause pipeline-id=N/A pipeline-name="my_pipeline"' error_code: PipelineInteractionUnreachable details: pipeline_name: my_pipeline request: /pause error: the pipeline disconnected while it was processing this HTTP request. This could be because the pipeline either (a) encountered a fatal error or panic, (b) was stopped, or (c) experienced network issues -- retrying might help in the last case. Alternatively, check the pipeline logs. Pipeline is currently unavailable: value: message: 'Error sending HTTP request to pipeline: deployment status is currently ''unavailable'' -- wait for it to become ''running'' or ''paused'' again Failed request: /pause pipeline-id=N/A pipeline-name="my_pipeline"' error_code: PipelineInteractionUnreachable details: pipeline_name: my_pipeline request: /pause error: deployment status is currently 'unavailable' -- wait for it to become 'running' or 'paused' again Pipeline is not deployed: value: message: Unable to interact with pipeline because the deployment status (stopped) indicates it is not (yet) fully provisioned pipeline-id=N/A pipeline-name="my_pipeline" error_code: PipelineInteractionNotDeployed details: pipeline_name: my_pipeline status: Stopped desired_status: Provisioned Response timeout: value: message: 'Error sending HTTP request to pipeline: timeout (10s) was reached: this means the pipeline took too long to respond -- this can simply be because the request was too difficult to process in time, or other reasons (e.g., deadlock): the pipeline logs might contain additional information (original send request error: Timeout while waiting for response) Failed request: /pause pipeline-id=N/A pipeline-name="my_pipeline"' error_code: PipelineInteractionUnreachable details: pipeline_name: my_pipeline request: /pause error: 'timeout (10s) was reached: this means the pipeline took too long to respond -- this can simply be because the request was too difficult to process in time, or other reasons (e.g., deadlock): the pipeline logs might contain additional information (original send request error: Timeout while waiting for response)' security: - JSON web token (JWT) or API key: [] post: tags: - Metrics & Debugging summary: Start a Samply profile description: Profile the pipeline using the Samply profiler for the next `duration_secs` seconds. operationId: start_samply_profile parameters: - name: pipeline_name in: path description: Unique pipeline name required: true schema: type: string - name: ordinal in: query description: In a multihost pipeline, the ordinal of the pipeline to sample. required: false schema: type: integer minimum: 0 - name: duration_secs in: query description: The number of seconds to sample for the profile. required: false schema: type: integer format: int64 minimum: 0 responses: '202': description: Started profiling the pipeline with the Samply tool '404': description: Pipeline with that name does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: Unknown pipeline name 'non-existent-pipeline' error_code: UnknownPipelineName details: pipeline_name: non-existent-pipeline '409': description: Samply profile collection is already in progress content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Disconnected during response: value: message: 'Error sending HTTP request to pipeline: the pipeline disconnected while it was processing this HTTP request. This could be because the pipeline either (a) encountered a fatal error or panic, (b) was stopped, or (c) experienced network issues -- retrying might help in the last case. Alternatively, check the pipeline logs. Failed request: /pause pipeline-id=N/A pipeline-name="my_pipeline"' error_code: PipelineInteractionUnreachable details: pipeline_name: my_pipeline request: /pause error: the pipeline disconnected while it was processing this HTTP request. This could be because the pipeline either (a) encountered a fatal error or panic, (b) was stopped, or (c) experienced network issues -- retrying might help in the last case. Alternatively, check the pipeline logs. Pipeline is currently unavailable: value: message: 'Error sending HTTP request to pipeline: deployment status is currently ''unavailable'' -- wait for it to become ''running'' or ''paused'' again Failed request: /pause pipeline-id=N/A pipeline-name="my_pipeline"' error_code: PipelineInteractionUnreachable details: pipeline_name: my_pipeline request: /pause error: deployment status is currently 'unavailable' -- wait for it to become 'running' or 'paused' again Pipeline is not deployed: value: message: Unable to interact with pipeline because the deployment status (stopped) indicates it is not (yet) fully provisioned pipeline-id=N/A pipeline-name="my_pipeline" error_code: PipelineInteractionNotDeployed details: pipeline_name: my_pipeline status: Stopped desired_status: Provisioned Response timeout: value: message: 'Error sending HTTP request to pipeline: timeout (10s) was reached: this means the pipeline took too long to respond -- this can simply be because the request was too difficult to process in time, or other reasons (e.g., deadlock): the pipeline logs might contain additional information (original send request error: Timeout while waiting for response) Failed request: /pause pipeline-id=N/A pipeline-name="my_pipeline"' error_code: PipelineInteractionUnreachable details: pipeline_name: my_pipeline request: /pause error: 'timeout (10s) was reached: this means the pipeline took too long to respond -- this can simply be because the request was too difficult to process in time, or other reasons (e.g., deadlock): the pipeline logs might contain additional information (original send request error: Timeout while waiting for response)' security: - JSON web token (JWT) or API key: [] /v0/pipelines/{pipeline_name}/stats: get: tags: - Metrics & Debugging summary: Get Pipeline Stats description: Retrieve statistics (e.g., performance counters) of a running or paused pipeline. operationId: get_pipeline_stats parameters: - name: pipeline_name in: path description: Unique pipeline name required: true schema: type: string responses: '200': description: Pipeline statistics retrieved successfully content: application/json: schema: $ref: '#/components/schemas/ControllerStatus' '404': description: Pipeline with that name does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: Unknown pipeline name 'non-existent-pipeline' error_code: UnknownPipelineName details: pipeline_name: non-existent-pipeline '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Disconnected during response: value: message: 'Error sending HTTP request to pipeline: the pipeline disconnected while it was processing this HTTP request. This could be because the pipeline either (a) encountered a fatal error or panic, (b) was stopped, or (c) experienced network issues -- retrying might help in the last case. Alternatively, check the pipeline logs. Failed request: /pause pipeline-id=N/A pipeline-name="my_pipeline"' error_code: PipelineInteractionUnreachable details: pipeline_name: my_pipeline request: /pause error: the pipeline disconnected while it was processing this HTTP request. This could be because the pipeline either (a) encountered a fatal error or panic, (b) was stopped, or (c) experienced network issues -- retrying might help in the last case. Alternatively, check the pipeline logs. Pipeline is currently unavailable: value: message: 'Error sending HTTP request to pipeline: deployment status is currently ''unavailable'' -- wait for it to become ''running'' or ''paused'' again Failed request: /pause pipeline-id=N/A pipeline-name="my_pipeline"' error_code: PipelineInteractionUnreachable details: pipeline_name: my_pipeline request: /pause error: deployment status is currently 'unavailable' -- wait for it to become 'running' or 'paused' again Pipeline is not deployed: value: message: Unable to interact with pipeline because the deployment status (stopped) indicates it is not (yet) fully provisioned pipeline-id=N/A pipeline-name="my_pipeline" error_code: PipelineInteractionNotDeployed details: pipeline_name: my_pipeline status: Stopped desired_status: Provisioned Response timeout: value: message: 'Error sending HTTP request to pipeline: timeout (10s) was reached: this means the pipeline took too long to respond -- this can simply be because the request was too difficult to process in time, or other reasons (e.g., deadlock): the pipeline logs might contain additional information (original send request error: Timeout while waiting for response) Failed request: /pause pipeline-id=N/A pipeline-name="my_pipeline"' error_code: PipelineInteractionUnreachable details: pipeline_name: my_pipeline request: /pause error: 'timeout (10s) was reached: this means the pipeline took too long to respond -- this can simply be because the request was too difficult to process in time, or other reasons (e.g., deadlock): the pipeline logs might contain additional information (original send request error: Timeout while waiting for response)' security: - JSON web token (JWT) or API key: [] /v0/pipelines/{pipeline_name}/support_bundle: get: tags: - Metrics & Debugging summary: Download Support Bundle description: 'Generate a support bundle for a pipeline. This endpoint collects various diagnostic data from the pipeline including circuit profile, heap profile, metrics, logs, stats, and connector statistics, and packages them into a single ZIP file for support purposes.' operationId: get_pipeline_support_bundle parameters: - name: pipeline_name in: path description: Unique pipeline name required: true schema: type: string - name: collect in: query description: 'Whether to collect new data from the running pipeline (default: true) When false, only previously collected data will be included in the bundle' required: false schema: type: boolean - name: limit in: query description: 'Maximum number of collections to include in the bundle, counted from the most recent. Must be at least 1; `limit=0` is rejected with HTTP 400. Omit the parameter to include every retained collection (which is capped server-side by `--support-data-retention`, default 3). With the default `collect=true`, `limit=1` returns only the collection gathered by this request. Combine with `collect=false` to return the most recent previously stored collections instead.' required: false schema: type: integer format: int64 nullable: true minimum: 0 - name: circuit_profile in: query description: 'Whether to collect circuit profile data (default: true)' required: false schema: type: boolean - name: heap_profile in: query description: 'Whether to collect heap profile data (default: true)' required: false schema: type: boolean - name: metrics in: query description: 'Whether to collect metrics data (default: true)' required: false schema: type: boolean - name: logs in: query description: 'Whether to collect logs data (default: true)' required: false schema: type: boolean - name: stats in: query description: 'Whether to collect stats data (default: true)' required: false schema: type: boolean - name: pipeline_config in: query description: 'Whether to collect pipeline configuration data (default: true)' required: false schema: type: boolean - name: system_config in: query description: 'Whether to collect system configuration data (default: true)' required: false schema: type: boolean - name: dataflow_graph in: query description: 'Whether to collect dataflow graph data (default: true)' required: false schema: type: boolean - name: pipeline_events in: query description: 'Whether to collect the pipeline monitor event history (default: true)' required: false schema: type: boolean responses: '200': description: Support bundle containing diagnostic information content: application/zip: schema: type: string format: binary '400': description: A query parameter was invalid (e.g., `limit=0`) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Pipeline with that name does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: Unknown pipeline name 'non-existent-pipeline' error_code: UnknownPipelineName details: pipeline_name: non-existent-pipeline '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Disconnected during response: value: message: 'Error sending HTTP request to pipeline: the pipeline disconnected while it was processing this HTTP request. This could be because the pipeline either (a) encountered a fatal error or panic, (b) was stopped, or (c) experienced network issues -- retrying might help in the last case. Alternatively, check the pipeline logs. Failed request: /pause pipeline-id=N/A pipeline-name="my_pipeline"' error_code: PipelineInteractionUnreachable details: pipeline_name: my_pipeline request: /pause error: the pipeline disconnected while it was processing this HTTP request. This could be because the pipeline either (a) encountered a fatal error or panic, (b) was stopped, or (c) experienced network issues -- retrying might help in the last case. Alternatively, check the pipeline logs. Response timeout: value: message: 'Error sending HTTP request to pipeline: timeout (10s) was reached: this means the pipeline took too long to respond -- this can simply be because the request was too difficult to process in time, or other reasons (e.g., deadlock): the pipeline logs might contain additional information (original send request error: Timeout while waiting for response) Failed request: /pause pipeline-id=N/A pipeline-name="my_pipeline"' error_code: PipelineInteractionUnreachable details: pipeline_name: my_pipeline request: /pause error: 'timeout (10s) was reached: this means the pipeline took too long to respond -- this can simply be because the request was too difficult to process in time, or other reasons (e.g., deadlock): the pipeline logs might contain additional information (original send request error: Timeout while waiting for response)' security: - JSON web token (JWT) or API key: [] /v0/pipelines/{pipeline_name}/time_series: get: tags: - Metrics & Debugging summary: Get Time Series Stats description: Retrieve time series for statistics of a running or paused pipeline. operationId: get_pipeline_time_series parameters: - name: pipeline_name in: path description: Unique pipeline name required: true schema: type: string responses: '200': description: Pipeline time series retrieved successfully content: application/json: schema: $ref: '#/components/schemas/TimeSeries' '404': description: Pipeline with that name does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: Unknown pipeline name 'non-existent-pipeline' error_code: UnknownPipelineName details: pipeline_name: non-existent-pipeline '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Disconnected during response: value: message: 'Error sending HTTP request to pipeline: the pipeline disconnected while it was processing this HTTP request. This could be because the pipeline either (a) encountered a fatal error or panic, (b) was stopped, or (c) experienced network issues -- retrying might help in the last case. Alternatively, check the pipeline logs. Failed request: /pause pipeline-id=N/A pipeline-name="my_pipeline"' error_code: PipelineInteractionUnreachable details: pipeline_name: my_pipeline request: /pause error: the pipeline disconnected while it was processing this HTTP request. This could be because the pipeline either (a) encountered a fatal error or panic, (b) was stopped, or (c) experienced network issues -- retrying might help in the last case. Alternatively, check the pipeline logs. Pipeline is currently unavailable: value: message: 'Error sending HTTP request to pipeline: deployment status is currently ''unavailable'' -- wait for it to become ''running'' or ''paused'' again Failed request: /pause pipeline-id=N/A pipeline-name="my_pipeline"' error_code: PipelineInteractionUnreachable details: pipeline_name: my_pipeline request: /pause error: deployment status is currently 'unavailable' -- wait for it to become 'running' or 'paused' again Pipeline is not deployed: value: message: Unable to interact with pipeline because the deployment status (stopped) indicates it is not (yet) fully provisioned pipeline-id=N/A pipeline-name="my_pipeline" error_code: PipelineInteractionNotDeployed details: pipeline_name: my_pipeline status: Stopped desired_status: Provisioned Response timeout: value: message: 'Error sending HTTP request to pipeline: timeout (10s) was reached: this means the pipeline took too long to respond -- this can simply be because the request was too difficult to process in time, or other reasons (e.g., deadlock): the pipeline logs might contain additional information (original send request error: Timeout while waiting for response) Failed request: /pause pipeline-id=N/A pipeline-name="my_pipeline"' error_code: PipelineInteractionUnreachable details: pipeline_name: my_pipeline request: /pause error: 'timeout (10s) was reached: this means the pipeline took too long to respond -- this can simply be because the request was too difficult to process in time, or other reasons (e.g., deadlock): the pipeline logs might contain additional information (original send request error: Timeout while waiting for response)' security: - JSON web token (JWT) or API key: [] /v0/pipelines/{pipeline_name}/time_series_stream: get: tags: - Metrics & Debugging summary: Stream Time Series description: 'Stream time series for statistics of a running or paused pipeline. Returns a snapshot of all existing time series data followed by a continuous stream of new time series data points as they become available. The response is in newline-delimited JSON format (NDJSON) where each line is a JSON object representing a single time series data point.' operationId: get_pipeline_time_series_stream parameters: - name: pipeline_name in: path description: Unique pipeline name required: true schema: type: string responses: '200': description: Pipeline time series stream established successfully content: application/x-ndjson: schema: type: string '404': description: Pipeline with that name does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: Unknown pipeline name 'non-existent-pipeline' error_code: UnknownPipelineName details: pipeline_name: non-existent-pipeline '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Disconnected during response: value: message: 'Error sending HTTP request to pipeline: the pipeline disconnected while it was processing this HTTP request. This could be because the pipeline either (a) encountered a fatal error or panic, (b) was stopped, or (c) experienced network issues -- retrying might help in the last case. Alternatively, check the pipeline logs. Failed request: /pause pipeline-id=N/A pipeline-name="my_pipeline"' error_code: PipelineInteractionUnreachable details: pipeline_name: my_pipeline request: /pause error: the pipeline disconnected while it was processing this HTTP request. This could be because the pipeline either (a) encountered a fatal error or panic, (b) was stopped, or (c) experienced network issues -- retrying might help in the last case. Alternatively, check the pipeline logs. Pipeline is currently unavailable: value: message: 'Error sending HTTP request to pipeline: deployment status is currently ''unavailable'' -- wait for it to become ''running'' or ''paused'' again Failed request: /pause pipeline-id=N/A pipeline-name="my_pipeline"' error_code: PipelineInteractionUnreachable details: pipeline_name: my_pipeline request: /pause error: deployment status is currently 'unavailable' -- wait for it to become 'running' or 'paused' again Pipeline is not deployed: value: message: Unable to interact with pipeline because the deployment status (stopped) indicates it is not (yet) fully provisioned pipeline-id=N/A pipeline-name="my_pipeline" error_code: PipelineInteractionNotDeployed details: pipeline_name: my_pipeline status: Stopped desired_status: Provisioned Response timeout: value: message: 'Error sending HTTP request to pipeline: timeout (10s) was reached: this means the pipeline took too long to respond -- this can simply be because the request was too difficult to process in time, or other reasons (e.g., deadlock): the pipeline logs might contain additional information (original send request error: Timeout while waiting for response) Failed request: /pause pipeline-id=N/A pipeline-name="my_pipeline"' error_code: PipelineInteractionUnreachable details: pipeline_name: my_pipeline request: /pause error: 'timeout (10s) was reached: this means the pipeline took too long to respond -- this can simply be because the request was too difficult to process in time, or other reasons (e.g., deadlock): the pipeline logs might contain additional information (original send request error: Timeout while waiting for response)' security: - JSON web token (JWT) or API key: [] components: schemas: StorageStatus: type: string description: 'Storage status. The storage status can only transition when the resources status is `Stopped`. ```text Cleared ───┐ ▲ │ /clear │ │ │ │ Clearing │ ▲ │ │ │ InUse ◄───┘ ```' enum: - Cleared - InUse - Clearing SampleStatistics: type: object description: One sample of time-series data. required: - t - r - m - s properties: m: type: integer format: int64 description: Memory usage in bytes. minimum: 0 r: type: integer format: int64 description: Records processed. minimum: 0 s: type: integer format: int64 description: Storage usage in bytes. minimum: 0 t: type: string format: date-time description: Sample time. InputEndpointStatus: type: object description: Input endpoint status information. required: - endpoint_name - config - metrics - paused - barrier properties: barrier: type: boolean description: Endpoint is currently a barrier to checkpointing and suspend. completed_frontier: allOf: - $ref: '#/components/schemas/CompletedWatermark' nullable: true config: $ref: '#/components/schemas/ShortEndpointConfig' endpoint_name: type: string description: Endpoint name. fatal_error: type: string description: The first fatal error that occurred at the endpoint. nullable: true health: allOf: - $ref: '#/components/schemas/ConnectorHealth' nullable: true metrics: $ref: '#/components/schemas/InputEndpointMetrics' parse_errors: type: array items: $ref: '#/components/schemas/ConnectorError' description: Recent parse errors on this endpoint. nullable: true paused: type: boolean description: Endpoint has been paused by the user. transport_errors: type: array items: $ref: '#/components/schemas/ConnectorError' description: Recent transport errors on this endpoint. nullable: true SuspendError: oneOf: - type: object required: - Permanent properties: Permanent: type: array items: $ref: '#/components/schemas/PermanentSuspendError' description: 'Pipeline does not support suspend-and-resume. These reasons only change if the pipeline''s configuration changes, e.g. if a pipeline has an input connector that does not support suspend-and-resume, and then that input connector is removed.' - type: object required: - Temporary properties: Temporary: type: array items: $ref: '#/components/schemas/TemporarySuspendError' description: 'Pipeline supports suspend-and-resume, but a suspend requested now will be delayed.' description: Whether a pipeline supports checkpointing and suspend-and-resume. TransactionStatus: type: string description: Transaction status summarized as a single value. enum: - NoTransaction - TransactionInProgress - CommitInProgress TimeSeries: type: object description: Time series to make graphs in the web console easier. required: - now - samples properties: now: type: string format: date-time description: Current time as of the creation of the structure. samples: type: array items: $ref: '#/components/schemas/SampleStatistics' description: 'Time series. These report 60 seconds of samples, one per second.' CommitProgressSummary: type: object description: Summary of transaction commit progress. required: - completed - in_progress - remaining - in_progress_processed_records - in_progress_total_records properties: completed: type: integer format: int64 description: Number of operators that have been fully flushed. minimum: 0 in_progress: type: integer format: int64 description: Number of operators that are currently being flushed. minimum: 0 in_progress_processed_records: type: integer format: int64 description: Number of records processed by operators that are currently being flushed. minimum: 0 in_progress_total_records: type: integer format: int64 description: Total number of records that operators that are currently being flushed need to process. minimum: 0 remaining: type: integer format: int64 description: Number of operators that haven't started flushing. minimum: 0 ConnectorHealth: type: object required: - status properties: description: type: string nullable: true status: $ref: '#/components/schemas/ConnectorHealthStatus' ProgramStatus: type: string description: Program compilation status. enum: - Pending - CompilingSql - SqlCompiled - CompilingRust - Success - SqlError - RustError - SystemError TransactionPhase: type: string description: Transaction phase. enum: - Started - Committed PipelineMonitorEventSelectedInfo: type: object description: 'Pipeline monitor event information which has a selected subset of optional fields. If an optional field is not selected (i.e., is `None`), it will not be serialized.' required: - event_id - recorded_at - deployment_resources_status - deployment_resources_desired_status - deployment_has_error - program_status - storage_status properties: deployment_error: allOf: - $ref: '#/components/schemas/ErrorResponse' nullable: true deployment_has_error: type: boolean deployment_resources_desired_status: $ref: '#/components/schemas/ResourcesDesiredStatus' deployment_resources_status: $ref: '#/components/schemas/ResourcesStatus' deployment_resources_status_details: nullable: true deployment_runtime_desired_status: allOf: - $ref: '#/components/schemas/RuntimeDesiredStatus' nullable: true deployment_runtime_status: allOf: - $ref: '#/components/schemas/RuntimeStatus' nullable: true deployment_runtime_status_details: nullable: true event_id: $ref: '#/components/schemas/PipelineMonitorEventId' program_status: $ref: '#/components/schemas/ProgramStatus' recorded_at: type: string format: date-time storage_status: $ref: '#/components/schemas/StorageStatus' storage_status_details: nullable: true ResourcesStatus: type: string description: 'Pipeline resources status. ```text /start (early start or provision check failed) ┌───┐ │ ▼ Stopped ◄────────── Stopping /start │ ▲ │ │ /stop?force=true │ │ OR: timeout (from Provisioning) ▼ │ OR: fatal runtime or resource error ⌛Provisioning ────────────│ OR: runtime status is Suspended │ │ │ │ ▼ │ Provisioned ─────────────┘ ``` ### Desired and actual status We use the desired state model to manage the lifecycle of a pipeline. In this model, the pipeline has two status attributes associated with it: the **desired** status, which represents what the user would like the pipeline to do, and the **current** status, which represents the actual (last observed) status of the pipeline. The pipeline runner service continuously monitors the desired status field to decide where to steer the pipeline towards. There are two desired statuses: - `Provisioned` (set by invoking `/start`) - `Stopped` (set by invoking `/stop?force=true`) The user can monitor the current status of the pipeline via the `GET /v0/pipelines/{name}` endpoint. In a typical scenario, the user first sets the desired status, e.g., by invoking the `/start` endpoint, and then polls the `GET /v0/pipelines/{name}` endpoint to monitor the actual status of the pipeline until its `deployment_resources_status` attribute changes to `Provisioned` indicating that the pipeline has been successfully provisioned, or `Stopped` with `deployment_error` being set.' enum: - Stopped - Provisioning - Provisioned - Stopping PermanentSuspendError: oneOf: - type: string enum: - StorageRequired - type: string enum: - EnterpriseFeature - type: object required: - UnsupportedInputEndpoint properties: UnsupportedInputEndpoint: type: string description: Reasons why a pipeline does not support suspend and resume operations. ErrorResponse: type: object description: Information returned by REST API endpoints on error. required: - message - error_code - details properties: details: description: 'Detailed error metadata. The contents of this field is determined by `error_code`.' error_code: type: string description: Error code is a string that specifies this error type. example: CodeSpecifyingErrorType message: type: string description: Human-readable error message. example: Explanation of the error that occurred. MemoryPressure: type: string description: 'Memory pressure level. The current memory pressure level is computed as a function of the current process resident set size (RSS) and the user-configured memory limit (`max_rss`). As the memory pressure level increases, the system will apply increasing backpressure to push state cached in memory to storage. - `Low`: less than 85% of the user-configured memory limit has been allocated. - `Moderate`: between 85% and 90% of the user-configured memory limit has been allocated. - `High`: between 90% and 95% of the user-configured memory limit has been allocated. - `Critical`: more than 95% of the user-configured memory limit has been allocated.' enum: - low - moderate - high - critical OutputEndpointStatus: type: object description: Output endpoint status information. required: - endpoint_name - config - metrics properties: config: $ref: '#/components/schemas/ShortEndpointConfig' encode_errors: type: array items: $ref: '#/components/schemas/ConnectorError' description: Recent encoding errors on this endpoint. nullable: true endpoint_name: type: string description: Endpoint name. fatal_error: type: string description: The first fatal error that occurred at the endpoint. nullable: true health: allOf: - $ref: '#/components/schemas/ConnectorHealth' nullable: true metrics: $ref: '#/components/schemas/OutputEndpointMetrics' transport_errors: type: array items: $ref: '#/components/schemas/ConnectorError' description: Recent transport errors on this endpoint. nullable: true ClockAdvanceResponse: type: object description: 'Response of `POST /clock/advance`: the new `NOW()` value as both milliseconds since epoch (signed; pre-1970 anchors yield negative values) and an RFC 3339 string.' required: - now_ms - now properties: now: type: string now_ms: type: integer format: int64 InputEndpointMetrics: type: object description: Performance metrics for an input endpoint. required: - total_bytes - total_records - buffered_records - buffered_bytes - num_transport_errors - num_parse_errors - end_of_input properties: buffered_bytes: type: integer format: int64 description: Number of bytes currently buffered by the endpoint (not yet consumed by the circuit). minimum: 0 buffered_records: type: integer format: int64 description: Number of records currently buffered by the endpoint (not yet consumed by the circuit). minimum: 0 end_of_input: type: boolean description: True if end-of-input has been signaled. num_parse_errors: type: integer format: int64 description: Number of parse errors. minimum: 0 num_transport_errors: type: integer format: int64 description: Number of transport errors. minimum: 0 total_bytes: type: integer format: int64 description: Total bytes pushed to the endpoint since it was created. minimum: 0 total_records: type: integer format: int64 description: Total records pushed to the endpoint since it was created. minimum: 0 ConnectorError: type: object required: - timestamp - index - message properties: index: type: integer format: int64 description: 'Sequence number of the error. The client can use this field to detect gaps in the error list reported by the pipeline. When the connector reports a large number of errors, the pipeline will only preserve and report the most recent errors of each kind.' minimum: 0 message: type: string description: Error message. tag: type: string description: 'Optional tag for the error. The tag is used to group errors by their type.' nullable: true timestamp: type: string format: date-time description: Timestamp when the error occurred, serialized as RFC3339 with microseconds. ConcurrentBootstrapPhase: type: string description: 'Phase of a concurrent bootstrap. `#[repr(u8)]` + `NoUninit` so it can be stored in a lock-free `Atomic`.' enum: - Inactive - ConcurrentBootstrapping - Synchronizing ConnectorTransactionPhase: type: object description: Connector transaction phase with debugging label. required: - phase properties: label: type: string description: Optional label for debugging. nullable: true phase: $ref: '#/components/schemas/TransactionPhase' GlobalControllerMetrics: type: object description: Global controller metrics. required: - state - bootstrap_in_progress - transaction_status - transaction_id - transaction_initiators - concurrent_bootstrap_phase - rss_bytes - memory_pressure - memory_pressure_epoch - cpu_msecs - uptime_msecs - start_time - incarnation_uuid - initial_start_time - storage_bytes - storage_mb_secs - runtime_elapsed_msecs - buffered_input_records - buffered_input_bytes - total_input_records - total_input_bytes - total_processed_records - total_processed_bytes - total_completed_records - output_stall_msecs - total_initiated_steps - total_completed_steps - pipeline_complete properties: bootstrap_in_progress: type: boolean description: The pipeline has been resumed from a checkpoint and is currently bootstrapping new and modified views. buffered_input_bytes: type: integer format: int64 description: Total number of bytes currently buffered by all endpoints. minimum: 0 buffered_input_records: type: integer format: int64 description: Total number of records currently buffered by all endpoints. minimum: 0 commit_progress: allOf: - $ref: '#/components/schemas/CommitProgressSummary' nullable: true concurrent_bootstrap_phase: $ref: '#/components/schemas/ConcurrentBootstrapPhase' concurrent_bootstrap_progress: allOf: - $ref: '#/components/schemas/CommitProgressSummary' nullable: true cpu_msecs: type: integer format: int64 description: CPU time used by the pipeline across all threads, in milliseconds. minimum: 0 incarnation_uuid: type: string format: uuid description: Uniquely identifies the pipeline process that started at start_time. initial_start_time: type: integer format: int64 description: Time at which the pipeline process from which we resumed started, in seconds since the epoch. minimum: 0 memory_pressure: $ref: '#/components/schemas/MemoryPressure' memory_pressure_epoch: type: integer format: int64 description: Memory pressure epoch. minimum: 0 output_stall_msecs: type: integer format: int64 description: 'If the pipeline is stalled because one or more output connectors'' output buffers are full, this is the number of milliseconds that the current stall has lasted. If this is nonzero, then the output connectors causing the stall can be identified by noticing `ExternalOutputEndpointMetrics::queued_records` is greater than or equal to `ConnectorConfig::max_queued_records`. In the ordinary case, the pipeline is not stalled, and this value is 0.' minimum: 0 pipeline_complete: type: boolean description: True if the pipeline has processed all input data to completion. rss_bytes: type: integer format: int64 description: Resident set size of the pipeline process, in bytes. minimum: 0 runtime_elapsed_msecs: type: integer format: int64 description: Time elapsed while the pipeline is executing a step, multiplied by the number of threads, in milliseconds. minimum: 0 start_time: type: integer format: int64 description: Time at which the pipeline process started, in seconds since the epoch. minimum: 0 state: $ref: '#/components/schemas/PipelineState' storage_bytes: type: integer format: int64 description: Current storage usage in bytes. minimum: 0 storage_mb_secs: type: integer format: int64 description: Storage usage integrated over time, in megabytes * seconds. minimum: 0 total_completed_records: type: integer format: int64 description: Total number of input records processed to completion. minimum: 0 total_completed_steps: type: integer format: int64 description: 'Number of steps whose input records have been processed to completion. A record is processed to completion if it has been processed by the DBSP engine and all outputs derived from it have been processed by all output connectors. # Interpretation This is a count, not a step number. If `total_completed_steps` is 0, no steps have been processed to completion. If `total_completed_steps > 0`, then the last step whose input records have been processed to completion is `total_completed_steps - 1`. A record that was ingested when `total_initiated_steps` was `n` is fully processed when `total_completed_steps >= n`.' minimum: 0 total_initiated_steps: type: integer format: int64 description: 'Number of steps that have been initiated. # Interpretation This is a count, not a step number. If `total_initiated_steps` is 0, no steps have been initiated. If `total_initiated_steps > 0`, then step `total_initiated_steps - 1` has been started and all steps previous to that have been completely processed by the circuit.' minimum: 0 total_input_bytes: type: integer format: int64 description: Total number of bytes received from all endpoints. minimum: 0 total_input_records: type: integer format: int64 description: Total number of records received from all endpoints. minimum: 0 total_processed_bytes: type: integer format: int64 description: Total bytes of input records processed by the DBSP engine. minimum: 0 total_processed_records: type: integer format: int64 description: Total number of input records processed by the DBSP engine. minimum: 0 transaction_id: type: integer format: int64 description: ID of the current transaction or 0 if no transaction is in progress. transaction_initiators: $ref: '#/components/schemas/TransactionInitiators' transaction_msecs: type: integer format: int64 description: 'Elapsed time in milliseconds, according to `transaction_status`: - [TransactionStatus::TransactionInProgress]: Time that this transaction has been in progress. - [TransactionStatus::CommitInProgress]: Time that this transaction has been committing.' nullable: true minimum: 0 transaction_records: type: integer format: int64 description: 'Number of records in this transaction, according to `transaction_status`: - [TransactionStatus::TransactionInProgress]: Number of records added so far. More records might be added. - [TransactionStatus::CommitInProgress]: Final number of records.' nullable: true minimum: 0 transaction_status: $ref: '#/components/schemas/TransactionStatus' uptime_msecs: type: integer format: int64 description: 'Time since the pipeline process started, including time that the pipeline was running or paused. This is the elapsed time since `start_time`.' minimum: 0 ClockAdvanceRequest: type: object description: 'Body of `POST /clock/advance`. `delta_ms` is unsigned; negative values fail JSON deserialization. `Some(0)` reads the current `NOW()` without moving it or rounding it; `Some(n)` advances by `n` ms; `None` (`null` or omitted) advances by one `clock_resolution`. Non-zero values round up to the next `clock_resolution` boundary, so a sub-resolution delta still moves the clock by one full tick.' properties: delta_ms: type: integer format: int64 nullable: true minimum: 0 ResourcesDesiredStatus: type: string enum: - Stopped - Provisioned PipelineMonitorEventId: type: string format: uuid description: Pipeline monitor event identifier. RuntimeStatus: type: string description: 'Runtime status of the pipeline. Of the statuses, only `Unavailable` is determined by the runner. All other statuses are determined by the pipeline and taken over by the runner.' enum: - Unavailable - Coordination - Standby - Initializing - AwaitingApproval - Bootstrapping - Replaying - Paused - Running - Suspended - ConcurrentBootstrapping - Synchronizing PipelineState: type: string description: Pipeline state. enum: - Paused - Running - Terminated ShortEndpointConfig: type: object description: Schema definition for endpoint config that only includes the stream field. required: - stream properties: stream: type: string description: The name of the stream. ControllerStatus: type: object description: 'Complete pipeline statistics returned by the `/stats` endpoint. This schema definition matches the serialized JSON structure from `adapters::controller::ControllerStatus`. The actual implementation with atomics and mutexes lives in the adapters crate, which uses ExternalControllerStatus to register this OpenAPI schema, making it available to pipeline-manager without requiring a direct dependency on the adapters crate.' required: - global_metrics - inputs - outputs properties: checkpoint_activity: allOf: - $ref: '#/components/schemas/CheckpointActivity' nullable: true global_metrics: $ref: '#/components/schemas/GlobalControllerMetrics' inputs: type: array items: $ref: '#/components/schemas/InputEndpointStatus' description: Input endpoint configs and metrics. outputs: type: array items: $ref: '#/components/schemas/OutputEndpointStatus' description: Output endpoint configs and metrics. permanent_checkpoint_errors: type: array items: $ref: '#/components/schemas/PermanentSuspendError' description: 'If the pipeline fundamentally cannot checkpoint (e.g. storage is not configured, or an input endpoint does not support suspend), the reasons are listed here. Unlike a checkpoint failure, this means *no* checkpoint can succeed until the pipeline configuration changes.' nullable: true suspend_error: allOf: - $ref: '#/components/schemas/SuspendError' nullable: true RuntimeDesiredStatus: type: string enum: - Unavailable - Coordination - Standby - Paused - Running - Suspended TransactionInitiators: type: object description: Information about entities that initiated the current transaction. required: - initiated_by_connectors properties: initiated_by_api: allOf: - $ref: '#/components/schemas/TransactionPhase' nullable: true initiated_by_connectors: type: object description: Transaction phases initiated by connectors, indexed by endpoint name. additionalProperties: $ref: '#/components/schemas/ConnectorTransactionPhase' transaction_id: type: integer format: int64 description: ID assigned to the transaction (None if no transaction is in progress). nullable: true CompletedWatermark: type: object description: A watermark that has been fully processed by the pipeline. required: - metadata - ingested_at - processed_at - completed_at properties: completed_at: type: string format: date-time description: Timestamp when all outputs produced from this input have been pushed to all output endpoints. ingested_at: type: string format: date-time description: Timestamp when the data was ingested from the wire. metadata: type: object description: Metadata that describes the position in the input stream (e.g., Kafka partition/offset pairs). processed_at: type: string format: date-time description: Timestamp when the data was processed by the circuit. OutputEndpointMetrics: type: object description: Performance metrics for an output endpoint. required: - transmitted_records - transmitted_bytes - queued_records - queued_batches - buffered_records - buffered_batches - num_encode_errors - num_transport_errors - total_processed_input_records - total_processed_steps - memory properties: batch_records_written: type: integer format: int64 description: 'Number of records written so far while the connector is processing a batch of updates. Resets to 0 after the batch is committed. `None` when the connector does not support batch-progress reporting.' nullable: true minimum: 0 buffered_batches: type: integer format: int64 description: Number of batches in the buffer. minimum: 0 buffered_records: type: integer format: int64 description: Number of records pushed to the output buffer. minimum: 0 memory: type: integer format: int64 description: Extra memory in use beyond that used for queuing records. minimum: 0 num_encode_errors: type: integer format: int64 description: Number of encoding errors. minimum: 0 num_transport_errors: type: integer format: int64 description: Number of transport errors. minimum: 0 queued_batches: type: integer format: int64 description: Number of queued batches. minimum: 0 queued_records: type: integer format: int64 description: Number of queued records. minimum: 0 total_processed_input_records: type: integer format: int64 description: 'The number of input records processed by the circuit. This metric tracks the end-to-end progress of the pipeline: the output of this endpoint is equal to the output of the circuit after processing `total_processed_input_records` records. In a multihost pipeline, this count reflects only the input records processed on the same host as the output endpoint, which is not usually meaningful.' minimum: 0 total_processed_steps: type: integer format: int64 description: 'The number of steps whose input records have been processed by the endpoint. This is meaningful in a multihost pipeline because steps are synchronized across all of the hosts. # Interpretation This is a count, not a step number. If `total_processed_steps` is 0, no steps have been processed to completion. If `total_processed_steps > 0`, then the last step whose input records have been processed to completion is `total_processed_steps - 1`. A record that was ingested in step `n` is fully processed when `total_processed_steps > n`.' minimum: 0 transmitted_bytes: type: integer format: int64 description: Bytes sent on the underlying transport. minimum: 0 transmitted_records: type: integer format: int64 description: Records sent on the underlying transport. minimum: 0 TemporarySuspendError: oneOf: - type: string enum: - Replaying - type: string enum: - Bootstrapping - type: string enum: - TransactionInProgress - type: object required: - InputEndpointBarrier properties: InputEndpointBarrier: type: string - type: string enum: - Coordination description: Reasons why a pipeline cannot be suspended at this time. ConnectorHealthStatus: type: string enum: - Healthy - Unhealthy PipelineMonitorEventFieldSelector: type: string enum: - all - status MetricsFormat: type: string description: 'Circuit metrics output format. - `prometheus`: [format](https://github.com/prometheus/docs/blob/4b1b80f5f660a2f8dc25a54f52a65a502f31879a/docs/instrumenting/exposition_formats.md) expected by Prometheus - `json`: JSON format' enum: - prometheus - json CheckpointActivity: oneOf: - type: object required: - status properties: status: type: string enum: - idle - type: object description: 'A checkpoint has been requested but is delayed for temporary reasons (e.g. replaying, bootstrapping, transaction in progress, or input endpoint barriers that require the coordinator to run steps).' required: - reasons - delayed_since - status properties: delayed_since: type: string format: date-time description: When the delay started (serialized as ISO 8601). reasons: type: array items: $ref: '#/components/schemas/TemporarySuspendError' description: Why the checkpoint cannot proceed yet. status: type: string enum: - delayed - type: object description: A checkpoint is currently being written to storage. required: - started_at - status properties: started_at: type: string format: date-time description: When the checkpoint write started (serialized as ISO 8601). status: type: string enum: - in_progress description: Current checkpoint activity state. discriminator: propertyName: status securitySchemes: JSON web token (JWT) or API key: type: http scheme: bearer bearerFormat: JWT description: "Use a JWT token obtained via an OAuth2/OIDC\n login workflow or an API key obtained via\n the `/v0/api-keys` endpoint."