Manage Connectors

This page offers a detailed list of operations for effectively managing your connectors.

Info

This page uses the serilog-sink connector as an example. Replace instanceTypeName with the unique identifier of your chosen connector. For more information on the instance type name, refer to the configuration page.

Create

Create a connector by sending a POST request to connectors/{connector_id}, where {connector_id} is a unique identifier of your choice for the connector.

POST /connectors/serilog-sink
Host: localhost:2113
Content-Type: application/json

{
  "name": "Demo Serilog Sink",
  "settings": {
    "instanceTypeName": "serilog-sink",
    "subscription:filter:scope": "stream",
    "subscription:filter:expression": "some-stream",
    "subscription:initialPosition": "earliest"
  }
}

When you start the connector using the Start command, and append an event to the stream some-stream, the connector will consume the event and log it to the console. Find out more about Subscription configuration.

Note

The name field is optional and can be used to provide a human-readable name for the connector. If not provided, the connector will be named after the connector ID.

Start

Start a connector by sending a POST request to connectors/{connector_id}/start, where {connector_id} is the unique identifier used when the connector was created.

POST /connectors/serilog-sink/start
Host: localhost:2113

You can also start from a specific position by providing the start position in the query parameter. Do this by sending a POST request to connectors/{connector_id}/start/{log_position} where {log_position} is the position from which to start consuming events.

POST /connectors/serilog-sink/start/32789
Host: localhost:2113

Note

If you do not provide a start position, the connector will start consuming events from an existing checkpoint position, defaulting to the subscription initial position if no checkpoint exists.

List

List all connectors by sending a GET request to /connectors.

GET /connectors
Host: localhost:2113
Content-Type: application/json

{
  "state": ["CONNECTOR_STATE_STOPPED", "CONNECTOR_STATE_RUNNING"],
  "instanceTypeName": ["serilog-sink"],
  "connectorId": ["serilog-sink"],
  "includeSettings": true,
  "paging": {
      "page": 1,
      "pageSize": 100
  }
}

You can paginate the results by specifying the pageSize and page parameters. Additionally, you can filter the results using the state, instanceType, and connectorId parameters.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "items": [
    {
      "connectorId": "http-sink",
      "name": "Demo HTTP Sink",
      "state": "CONNECTOR_STATE_STOPPED",
      "stateTimestamp": "2024-08-13T12:21:50.506102900Z",
      "settings": {
        "instanceTypeName": "http-sink",
        "url": "http://localhost:8080/sink",
        "transformer:Enabled": "true",
        "transformer:Function": "ZnVuY3Rpb24gdHJhbnNmb3JtKHJlY29yZCkgewogIGxldCB7IG1ha2UsIG1vZGVsIH0gPSByZWNvcmQudmFsdWUudmVoaWNsZTsKICByZWNvcmQuc2NoZW1hSW5mby5zdWJqZWN0ID0gJ1ZlaGljbGUnOwogIHJlY29yZC52YWx1ZS52ZWhpY2xlLm1ha2Vtb2RlbCA9IGAke21ha2V9ICR7bW9kZWx9YDsKfQ==",
        "subscription:filter:scope": "stream",
        "subscription:filter:expression": "^\\$connectors\\/[^\\/]+\\/leases"
      },
      "settingsTimestamp": "2024-08-13T12:21:50.506102900Z"
    },
    {
      "connectorId": "serilog-sink",
      "name": "Demo Serilog Sink",
      "state": "CONNECTOR_STATE_RUNNING",
      "stateTimestamp": "2024-08-13T12:21:47.459327600Z",
      "settings": {
        "instanceTypeName": "serilog-sink",
        "subscription:filter:scope": "stream",
        "subscription:filter:expression": "some-stream",
        "subscription:initialPosition": "earliest"
      },
      "settingsTimestamp": "2024-08-13T12:21:47.366197400Z",
      "position": 16829
    }
  ],
  "totalCount": 2,
  "paging": {
    "page": 1,
    "pageSize": 100
  }
}

The following states are available:

State	Description
CONNECTOR_STATE_UNKNOWN	The state of the connector is unknown.
CONNECTOR_STATE_ACTIVATING	The connector is in the process of being activated.
CONNECTOR_STATE_RUNNING	The connector is currently running.
CONNECTOR_STATE_DEACTIVATING	The connector is in the process of being deactivated.
CONNECTOR_STATE_STOPPED	The connector is currently stopped.

View settings

View the settings for a connector by sending a GET request to /connectors/{connector_id}/settings, where {connector_id} is the unique identifier used when the connector was created.

GET /connectors/serilog-sink/settings
Host: localhost:2113

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "settings": {
    "instanceTypeName": "serilog-sink",
    "subscription:filter:scope": "stream",
    "subscription:filter:expression": "some-stream",
    "subscription:initialPosition": "latest"
  },
  "settingsUpdateTime": "2024-08-14T18:12:16.500822500Z"
}

Reset

Reset a connector by sending a POST request to /connectors/{connector_id}/reset, where {connector_id} is the unique identifier used when the connector was created.

POST /connectors/serilog-sink/reset
Host: localhost:2113

You can also reset the connector to a specific position by providing the reset position in the query parameter. Do this by sending a POST request to /connectors/{connector_id}/reset/{log_position} where {log_position} is the position to which the connector should be reset.

POST /connectors/serilog-sink/reset/25123
Host: localhost:2113

Note

If no reset position is provided, the connector will reset the position to the beginning of the stream.

Stop

Stop a connector by sending a POST request to /connectors/{connector_id}/stop, where {connector_id} is the unique identifier used when the connector was created.

POST /connectors/serilog-sink/stop
Host: localhost:2113

Reconfigure

Reconfigure an existing connector by sending a PUT request to /connectors/{connector_id}/settings, where {connector_id} is the unique identifier used when the connector was created. This endpoint allows you to modify the settings of a connector without having to delete and recreate it.

PUT /connectors/serilog-sink/settings
Host: localhost:2113
Content-Type: application/json

{
  "instanceTypeName": "serilog-sink",
  "logging:enabled": "false"
}

For a comprehensive list of available configuration options available for all sinks, please refer to the Connector Settings page.

Note

The connector must be stopped before reconfiguring. If the connector is running, the reconfigure operation will fail. Make sure to Stop the connector before attempting to reconfigure it.

Delete

Delete a connector by sending a DELETE request to /connectors/{connector_id}, where {connector_id} is the unique identifier used when the connector was created.

DELETE /connectors/serilog-sink
Host: localhost:2113

Rename

To rename a connector, send a PUT request to /connectors/{connector_id}/rename, where {connector_id} is the unique identifier used when the connector was created.

PUT /connectors/serilog-sink/rename
Host: localhost:2113
Content-Type: application/json

{
  "name": "New connector name"
}