Skip to main content

Pipelines

A pipeline is the configuration a node runs to move traffic, connecting components such as UDP sockets, TUN interfaces and error correction encoders into a data flow. Each start of a pipeline creates a new run, with its own logs and telemetry. Use this service to create, change, start and stop pipelines on any node, and to follow their changes, logs and telemetry.

Get pipelines​

Lists all pipelines on the node.

GET/v1/nodes/{node_id}/pipelines
Path parameters
  • node_idstring

    ID of the node to list the pipelines of.

Example
import { NanopingClient } from "@nanoping/api";

const client = new NanopingClient({ baseUrl: "http://127.0.0.1:10565" });

const response = await client.pipelines.getPipelines({
  nodeId: "3f2b1c9e-8d4a-4f6b-9c2e-1a7d5e8b0c4f"
});
Response
  • pipelinesPipeline[]

    The pipelines, in no particular order.

Get pipeline by id​

Get one pipeline. Fails with a not found error if it does not exist.

GET/v1/nodes/{node_id}/pipelines/{id}
Path parameters
  • node_idstring

    ID of the node that hosts the pipeline.

  • idstring

    ID of the pipeline.

Example
import { NanopingClient } from "@nanoping/api";

const client = new NanopingClient({ baseUrl: "http://127.0.0.1:10565" });

const response = await client.pipelines.getPipelineById({
  nodeId: "3f2b1c9e-8d4a-4f6b-9c2e-1a7d5e8b0c4f",
  id: "3f2b1c9e-8d4a-4f6b-9c2e-1a7d5e8b0c4f"
});
Response
  • pipelinePipeline

    The pipeline with the given ID.

Get pipeline by name​

Get one pipeline by name. Fails with a not found error if no pipeline, or more than one, has that name.

GET/v1/nodes/{node_id}/pipelines-by-name/{name}
Path parameters
  • node_idstring

    ID of the node that hosts the pipeline.

  • namestring

    Exact name of the pipeline. Example: UDP tunnel

Example
import { NanopingClient } from "@nanoping/api";

const client = new NanopingClient({ baseUrl: "http://127.0.0.1:10565" });

const response = await client.pipelines.getPipelineByName({
  nodeId: "3f2b1c9e-8d4a-4f6b-9c2e-1a7d5e8b0c4f",
  name: "UDP tunnel"
});
Response
  • pipelinePipeline

    The pipeline with the given name.

Get pipeline by run id​

Get the pipeline that a run belongs to. An unknown run fails with a timeout error.

GET/v1/nodes/{node_id}/pipeline-runs/{id}
Path parameters
  • node_idstring

    ID of the node that hosts the pipeline.

  • idstring

    ID of the run.

Example
import { NanopingClient } from "@nanoping/api";

const client = new NanopingClient({ baseUrl: "http://127.0.0.1:10565" });

const response = await client.pipelines.getPipelineByRunId({
  nodeId: "3f2b1c9e-8d4a-4f6b-9c2e-1a7d5e8b0c4f",
  id: "3f2b1c9e-8d4a-4f6b-9c2e-1a7d5e8b0c4f"
});
Response
  • pipelinePipeline

    The pipeline of the given run.

Create pipeline​

Create a pipeline from a JSON configuration and return it. The pipeline is not started. Fails with an invalid argument error if the configuration is invalid or the CPU pin is not a thread of the node.

POST/v1/nodes/{node_id}/pipelines
Path parameters
  • node_idstring

    ID of the node to create the pipeline on.

Request body
  • namestring

    Name of the pipeline. Example: UDP tunnel

  • jsonConfigstring

    The pipeline configuration as a JSON string.

  • restartPolicyRestartPolicy

    The restart policy of the pipeline. Leave unset to never restart.

  • startupPolicyStartupPolicy

    The startup policy of the pipeline. Leave unset to start it manually only.

  • defaultLoggingLevelLevelone of optional_default_logging_level

    The default logging level.

  • nodeReferenceIdstringone of optional_node_reference_id

    ID of the related node.

  • instructionsTimeoutint32one of optional_instructions_timeout

    The timeout in seconds. Must be greater than 0. Example: 30

  • cpuPinuint32one of optional_cpu_pin

    Zero indexed CPU thread number. Must be lower than the node's thread count.

  • performanceModeboolone of optional_performance_mode

    True to run the pinned thread in performance mode.

Example
import { NanopingClient } from "@nanoping/api";

const client = new NanopingClient({ baseUrl: "http://127.0.0.1:10565" });

const response = await client.pipelines.createPipeline({
  nodeId: "3f2b1c9e-8d4a-4f6b-9c2e-1a7d5e8b0c4f",
  name: "UDP tunnel",
  jsonConfig: "<pipeline configuration JSON>",
  restartPolicy: {
    never: {}
  },
  startupPolicy: {
    manual: {}
  },
  defaultLoggingLevel: "STATE",
  nodeReferenceId: "3f2b1c9e-8d4a-4f6b-9c2e-1a7d5e8b0c4f",
  instructionsTimeout: 30,
  cpuPin: 0,
  performanceMode: false
});
Response
  • pipelinePipeline

    The new pipeline, including its generated id.

Update pipeline​

Replace the settings of a pipeline and return the updated pipeline. If the pipeline is running and its configuration changed, the new configuration is applied to the current run. If that is not possible, the call fails because the pipeline is running, unless a restart is forced.

PUT/v1/nodes/{node_id}/pipelines/{id}
Path parameters
  • node_idstring

    ID of the node that hosts the pipeline.

  • idstring

    ID of the pipeline to update.

Request body
  • namestring

    New name of the pipeline. Example: UDP tunnel

  • jsonConfigstring

    New pipeline configuration as a JSON string.

  • restartPolicyRestartPolicy

    New restart policy of the pipeline. Unset means never restart.

  • startupPolicyStartupPolicy

    New startup policy of the pipeline. Unset means start manually only.

  • defaultLoggingLevelLevel

    New default logging level of the pipeline. Unset means STATE, not the INFO default used on create.

  • instructionsTimeoutint32

    New time in seconds before a pipeline instruction is considered timed out. Must be greater than 0. Example: 30

  • cpuPinuint32one of optional_cpu_pin

    Zero indexed CPU thread number. Must be lower than the node's thread count.

  • performanceModeboolone of optional_performance_mode

    True to run the pinned thread in performance mode.

  • nodeReferenceIdstringone of optional_node_reference_id

    ID of the related node.

  • forceRestartbool

    If true and the pipeline is running, the pipeline is restarted when the new configuration cannot be applied to the current run. The call then returns once the new run is running.

Example
import { NanopingClient } from "@nanoping/api";

const client = new NanopingClient({ baseUrl: "http://127.0.0.1:10565" });

const response = await client.pipelines.updatePipeline({
  nodeId: "3f2b1c9e-8d4a-4f6b-9c2e-1a7d5e8b0c4f",
  id: "3f2b1c9e-8d4a-4f6b-9c2e-1a7d5e8b0c4f",
  name: "UDP tunnel",
  jsonConfig: "<pipeline configuration JSON>",
  restartPolicy: {
    never: {}
  },
  startupPolicy: {
    manual: {}
  },
  defaultLoggingLevel: "STATE",
  instructionsTimeout: 30,
  cpuPin: 0,
  performanceMode: false,
  nodeReferenceId: "3f2b1c9e-8d4a-4f6b-9c2e-1a7d5e8b0c4f",
  forceRestart: false
});
Response
  • pipelinePipeline

    The pipeline after the update.

Delete pipeline​

Delete a pipeline. Fails with a not found error if it does not exist.

DELETE/v1/nodes/{node_id}/pipelines/{id}
Path parameters
  • node_idstring

    ID of the node that hosts the pipeline.

  • idstring

    ID of the pipeline to delete.

Example
import { NanopingClient } from "@nanoping/api";

const client = new NanopingClient({ baseUrl: "http://127.0.0.1:10565" });

await client.pipelines.deletePipeline({
  nodeId: "3f2b1c9e-8d4a-4f6b-9c2e-1a7d5e8b0c4f",
  id: "3f2b1c9e-8d4a-4f6b-9c2e-1a7d5e8b0c4f"
});
Response

No fields.

Start pipeline​

Start a pipeline and return its new run once it is running. Fails if the pipeline is unknown, already started, or does not reach the running state within 10 seconds.

Starting a pipeline creates a new run. To see what the run does, follow its log with the run ID the call returns. The client libraries do both in one step.

POST/v1/nodes/{node_id}/pipelines/{id}/start
Path parameters
  • node_idstring

    ID of the node that hosts the pipeline.

  • idstringone of pipeline_identifier

    ID of the pipeline.

Example
import { NanopingClient, runPipeline } from "@nanoping/api";

const client = new NanopingClient({ baseUrl: "http://127.0.0.1:10565" });

// Start the pipeline and print the log of the new run as it is written.
const nodeId = "3f2b1c9e-8d4a-4f6b-9c2e-1a7d5e8b0c4f";
const pipelineId = "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f";
for await (const message of runPipeline(client, nodeId, pipelineId)) {
  console.log(message.level, message.message);
}
POST/v1/nodes/{node_id}/pipelines-by-name/{name}/start
Path parameters
  • node_idstring

    ID of the node that hosts the pipeline.

  • namestringone of pipeline_identifier

    Exact name of the pipeline. Fails if more than one pipeline has this name. Example: UDP tunnel

Example
import { NanopingClient, runPipeline } from "@nanoping/api";

const client = new NanopingClient({ baseUrl: "http://127.0.0.1:10565" });

// Start the pipeline and print the log of the new run as it is written.
const nodeId = "3f2b1c9e-8d4a-4f6b-9c2e-1a7d5e8b0c4f";
const pipelineId = "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f";
for await (const message of runPipeline(client, nodeId, pipelineId)) {
  console.log(message.level, message.message);
}
Response
  • runIdstring

    ID of the new run.

Stop pipeline​

Stop a pipeline, found by its ID, its name or its current run. Returns once the stop is requested, without waiting for the run to end. Fails if the pipeline is unknown or already stopped.

POST/v1/nodes/{node_id}/pipelines/{id}/stop
Path parameters
  • node_idstring

    ID of the node that hosts the pipeline.

  • idstringone of pipeline_identifier

    ID of the pipeline.

Example
import { NanopingClient } from "@nanoping/api";

const client = new NanopingClient({ baseUrl: "http://127.0.0.1:10565" });

await client.pipelines.stopPipeline({
  nodeId: "3f2b1c9e-8d4a-4f6b-9c2e-1a7d5e8b0c4f",
  id: "3f2b1c9e-8d4a-4f6b-9c2e-1a7d5e8b0c4f"
});
POST/v1/nodes/{node_id}/pipelines-by-name/{name}/stop
Path parameters
  • node_idstring

    ID of the node that hosts the pipeline.

  • namestringone of pipeline_identifier

    Exact name of the pipeline. Fails if more than one pipeline has this name. Example: UDP tunnel

Example
import { NanopingClient } from "@nanoping/api";

const client = new NanopingClient({ baseUrl: "http://127.0.0.1:10565" });

await client.pipelines.stopPipeline({
  nodeId: "3f2b1c9e-8d4a-4f6b-9c2e-1a7d5e8b0c4f",
  id: "3f2b1c9e-8d4a-4f6b-9c2e-1a7d5e8b0c4f"
});
POST/v1/nodes/{node_id}/pipeline-runs/{run_id}/stop
Path parameters
  • node_idstring

    ID of the node that hosts the pipeline.

  • run_idstringone of pipeline_identifier

    ID of the pipeline's current run.

Example
import { NanopingClient } from "@nanoping/api";

const client = new NanopingClient({ baseUrl: "http://127.0.0.1:10565" });

await client.pipelines.stopPipeline({
  nodeId: "3f2b1c9e-8d4a-4f6b-9c2e-1a7d5e8b0c4f",
  id: "3f2b1c9e-8d4a-4f6b-9c2e-1a7d5e8b0c4f"
});
Response

No fields.

Stream pipelines​

Stream changes to the pipelines of a node. Nothing is sent when the stream opens, so get the pipelines first for the current list. An event is sent each time a pipeline is created, updated or deleted, and when a pipeline starts or stops.

GET/v1/streams/nodes/{node_id}/pipelines

Server-sent events. A : ready comment is sent when the stream is ready, then each message is a data: line holding the response below. A failure after that is an error event.

Path parameters
  • node_idstring

    ID of the node to stream pipeline changes from.

Example
import { NanopingClient } from "@nanoping/api";

const client = new NanopingClient({ baseUrl: "http://127.0.0.1:10565" });

for await (const response of client.pipelines.streamPipelines({
  nodeId: "3f2b1c9e-8d4a-4f6b-9c2e-1a7d5e8b0c4f"
})) {
}
Response messages
  • createStreamPipelinesCreateEventone of event

    Sent when a pipeline is created.

  • updateStreamPipelinesUpdateEventone of event

    Sent when a pipeline is changed, started or stopped.

  • deleteStreamPipelinesDeleteEventone of event

    Sent when a pipeline is deleted.

Open log stream​

Stream the log messages of a pipeline run. The requested number of past lines is sent first, then new messages as they are logged.

GET/v1/streams/nodes/{node_id}/pipeline-runs/{run_id}/logs

Server-sent events. A : ready comment is sent when the stream is ready, then each message is a data: line holding the response below. A failure after that is an error event.

Path parameters
  • node_idstring

    ID of the node that hosts the run.

  • run_idstring

    ID of the run to stream logs from.

Query parameters
  • optionsOptions

    Stream options, such as how many past lines to send first. Leave unset to receive only new messages.

Example
import { NanopingClient } from "@nanoping/api";

const client = new NanopingClient({ baseUrl: "http://127.0.0.1:10565" });

for await (const response of client.pipelines.openLogStream({
  nodeId: "3f2b1c9e-8d4a-4f6b-9c2e-1a7d5e8b0c4f",
  runId: "3f2b1c9e-8d4a-4f6b-9c2e-1a7d5e8b0c4f",
  options: {
    lines: "0"
  }
})) {
}
Response messages
  • messagesMessage[]

    The log messages.

Open telemetry stream​

Streams telemetry samples (metrics and KPI values) of a pipeline run at regular intervals while the run is active. The stream ends with an error when the run stops, when the run is unknown, or when the node disconnects.

GET/v1/streams/nodes/{node_id}/pipeline-runs/{run_id}/telemetry

Server-sent events. A : ready comment is sent when the stream is ready, then each message is a data: line holding the response below. A failure after that is an error event.

Path parameters
  • node_idstring

    ID of the node that hosts the run.

  • run_idstring

    ID of the run to stream telemetry from.

Example
import { NanopingClient } from "@nanoping/api";

const client = new NanopingClient({ baseUrl: "http://127.0.0.1:10565" });

for await (const response of client.pipelines.openTelemetryStream({
  nodeId: "3f2b1c9e-8d4a-4f6b-9c2e-1a7d5e8b0c4f",
  runId: "3f2b1c9e-8d4a-4f6b-9c2e-1a7d5e8b0c4f"
})) {
}
Response messages
  • metricCollectionsCollection[]

    The metrics of the run.

  • kpisKpi[]

    The KPI values of the run.

  • timestamptimestamp

    When the sample was taken.