How can we set up a dev environment for step debugging Conduit Connectors?

[nickchomey]

I'd like to make a connector of my own and perhaps even contribute to some existing ones, but I dont know how to step debug the connectors given that you run the conduit binary, which fetches/includes the connector binaries.

Could anyone please provide some tips?

In fact, I think this would be a very good topic to make an official doc for.

[hariso]

which fetches/includes the connector binaries

Can you clarify this part please?

But generally, for built-in (included) plugins, you can use your IDE and simply put breakpoints. As for the standalone plugins: they are, essentially, just compiled that are being run, so you can use remote debugging for them. The instructions for that depend on the IDE.

[nickchomey]

Sorry, Im quite sure that I just wrote clumsily.

Yes, I'm talking about standalone plugins. I can generally step debug a "primary" binary, but don't know how to step debug when a binary executes another binary, such as with the standalone plugins.

I use vs code, but I think that most ides use delve. If you could at least point me in the rejght direction of some documentation on how to do this, it would be very appreciated. But I do think it would be valuable to document setting up a basic dev environment for, say, vscode and maybe goland. It would allow people get up to speed more quickly (or at all), and be able to contirbute to conduit!

Thanks!

[lovromazgon]

@nickchomey you might have missed my answer, let me know if that's what you were looking for.

[lovromazgon]

I've debugged standalone plugins in the past, I've quickly compiled the approach I used. Note that this is a bit experimental, when I tried it out now, the plugin didn't finish gracefully for some reason and the Conduit process had to be killed. Nevertheless, debugging itself should work.

1. Install delve.

Full guide: https://github.com/go-delve/delve/tree/master/Documentation/installation

TL;DR:

go install https://github.com/go-delve/delve@latest

2. Wrap connector binary in a script that runs it using delve.

For this I suggest moving the standalone connector binary into a sub-folder in connectors, so Conduit doesn't load it directly (it only loads binaries it finds directly in the connectors folder). You should end up with something like this:

my-conduit-path
├── conduit                        # conduit binary
└── connectors
    ├── bin
    │   └── conduit-connector-file # connector binary
    └── conduit-connector-file.sh  # entrypoint that wraps connector in delve call

The contents of conduit-connector-file.sh:

#!/usr/bin/env bash
BASEDIR=$(dirname "$0")
dlv --listen=:9876 --headless=true --api-version=2 --accept-multiclient --log-dest=2 exec "$BASEDIR/bin/conduit-connector-file"

This will run delve on port 9876 and prepare it for remote debugging.

3. Run Conduit and debug the plugin

When starting Conduit, it first scans the connectors folder, runs each connector and fetches its specifications. The connector will block though, because delve is waiting for a remote debugger to attach and continue the execution. So right after starting Conduit you need to attach to the plugin and unblock it:

$ dlv connect :9876
(dlv) continue
(dlv) exit
Remote process has exited. Would you like to kill the headless instance? [Y/n] y

Assuming you have a pipeline configuration file that will use this standalone plugin, you need to attach a second time to actually debug it while the pipeline is running (so again dlv connect :9876 like above). Then you can set any breakpoints you wish. If you prefer, you can also use an IDE to do this instead of the CLI interface.

Keep in mind that Conduit waits for a limited amount of time for the plugin to start and do the handshake (I think 1 minute?), after that it will consider it broken and detach from the process, so you need to be relatively quick to attach to the plugin and advance execution.

[nickchomey]

I've submitted a PR to add a debug build, but nothing else. I don't know what to do to put all of the above in a make file - you have to have at least 2 terminals, unless there's a way to start conduit in the background somehow? You're welcome to suggest/submit improvements

ConduitIO/conduit-connector-template#48

[gedw99]

https://github.com/cirello-io/runner will do it but it’s not needed . 2 terminals is fine and I doubt they want a procfile in the main repo .

[hariso]

I don't think we need to do anything special about Conduit, because it's easy to debug an application you yourself are running. I guess you can just run Conduit in debug mode using VS Code. The problem with connectors is that Conduit is running them when needed, so you don't know when to attach to the connector processes.

[nickchomey]

I actually was not able to debug conduit itself yesterday. I followed the same process as for the connectors bug it kept freezing with some warning about debugging optimized code (even though I built it with the non-optimized flags).

I suppose I could try just launching a debug process for conduit without building a binary - as you normally would for debugging go applications - but I'm not sure how to load connectors when doing that

Any suggestions?

[hariso]

I'm using GoLand, and there I just use the debug option. No special setup at all needed, GoLand does everything. Nothing should change for connector, you still can use the same approach as above to debug connectors.

[nickchomey]

It was later suggested that we just include connectors we're developing as built-in connectors rather than standalone. This avoids all of the difficulties with Delve etc...

The docs are straightforward: https://conduit.io/docs/connectors/additional-built-in-plugins/

For my use-case of mysql and surrealdb you just do the following:

package main

import (
	"github.com/conduitio/conduit/pkg/conduit"
	mysql "github.com/conduitio-labs/conduit-connector-mysql"
	surrealdb "github.com/nickchomey/conduit-connector-surrealdb"
)

func main() {
	// Get the default configuration, including all built-in connectors
	cfg := conduit.DefaultConfig()

	cfg.ConnectorPlugins["mysql"] = mysql.Connector
	cfg.ConnectorPlugins["surrealdb"] = surrealdb.Connector


	conduit.Serve(cfg)
}

If you want to step debug the local dev version of these packages, just use replace

replace (
	github.com/conduitio-labs/conduit-connector-mysql v0.1.0 => ~/conduitproject/connectors/conduit-connector-mysql
	github.com/conduitio/conduit v0.12.0 => ~/conduitproject/conduit
	github.com/nickchomey/conduit-connector-surrealdb v0.1.0 => ~/conduitproject/connectors/conduit-connector-surrealdb
)

You can then add breakpoints to this main.go file, the core conduit files, or the connector files. And just launch main.go with VS Code's debugger with a launch.json config like this (feel free to change ${file} to a specific path etc...

        {
            "name": "Launch current main.go",
            "type": "go",
            "request": "launch",
            "mode": "auto",
            "program": "${file}",
            "showLog": true,
            "env": {},
            "args": [],
            "trace": "verbose",
            "debugAdapter": "dlv-dap"
        },