sysdig-go

sysdig-go is a Go client library for accessing the Sysdig and IBM Cloud Monitoring APIs.

Installation

sysdig-go supports go >=1.16.

go get github.com/trinchan/sysdig-go

will resolve and add the package to the current development module, along with its dependencies.

Alternatively the same can be achieved if you use import in a package:

import "github.com/trinchan/sysdig-go/sysdig"

and run go get without parameters.

Implemented APIs

Base	Get	List	Create	Delete	Update	Other	Service	Description
/team	✓	✓	x	✓	x	ListUsers, Infrastructure	client.Teams	Information about teams, users, and usage
/user/me	✓	x	x	x	x	x	client.Users	Information about the current user
/token	✓	x	x	x	x	x	client.Users	Retrieves the current user's access token
/agents/connected	✓	x	x	x	x	x	client.Users	Rerieves the connected Agents
/alerts	✓	✓	✓	x	x	x	client.Alerts	Manage alert configurations
/v3/dashboards	✓	✓	✓	✓	✓	Favorite, Transfer	client.Dashboards	Manage dashboard configurations
/v2/events	✓	✓	✓	✓	x	x	client.Events	Manage event notifications
/notificationChannels	✓	✓	✓	✓	x	x	client.NotificationChannels	Manage notification channels
/prometheus	✓	✓	x	x	x	x	client.Prometheus	Prometheus HTTP API

Usage

import "github.com/trinchan/sysdig-go/sysdig"

Construct a new Sysdig client, then use the various services on the client to access different parts of the API. For example:

package main

import (
	"context"
	"fmt"

	"github.com/trinchan/sysdig-go/sysdig"
	"github.com/trinchan/sysdig-go/sysdig/authentication/accesstoken"
)

func main() {
	accessToken := "YOUR_ACCESS_TOKEN"
	authenticator, err := accesstoken.Authenticator(accessToken)
	if err != nil {
		// handle error
	}
	client, err := sysdig.NewClient(authenticator)
	if err != nil {
		// handle error
	}

	// Get the current user
	me, _, err := client.Users.Me(context.Background())
	if err != nil {
		// handle error
	}
	fmt.Printf("Logged in as %s %s", me.User.FirstName, me.User.LastName)
}

Some API methods have optional parameters that can be passed. For example:

package main

import (
	"context"
	"fmt"

	"github.com/trinchan/sysdig-go/sysdig"
	"github.com/trinchan/sysdig-go/sysdig/authentication/accesstoken"
)

func main() {
	accessToken := "YOUR_ACCESS_TOKEN"
	authenticator, err := accesstoken.Authenticator(accessToken)
	if err != nil {
		// handle error
	}
	client, err := sysdig.NewClient(authenticator)
	if err != nil {
		// handle error
	}

	// Create an event
	opts := sysdig.EventOptions{
		Name:        "Event Name",
		Description: "Event Description",
		Severity:     sysdig.SeverityInfo,
	}
	event, _, err := client.Events.Create(context.Background(), opts)
	if err != nil {
		// handle error
	}
	fmt.Printf("Created event: %s", event.Event.ID)
}

The services of a client divide the API into logical chunks and correspond roughly to the structure of the Sysdig API.

NOTE: Using the context package, one can easily pass cancellation signals and deadlines to various services of the client for handling a request. In case there is no context available, then context.Background() can be used as a starting point.

For more sample code snippets, head over to the example directory.

Authentication

The sysdig-go library handles authentication through an Authenticator interface defined in the authentication package. When creating a new client, pass an authentication.Authenticator that can handle authentication for you. There are two methods of authentication supported.

The accesstoken subpackage authenticates each request with the provided Sysdig API Token.

package main

import (
	"context"
	"fmt"

	"github.com/trinchan/sysdig-go/sysdig"
	"github.com/trinchan/sysdig-go/sysdig/authentication/accesstoken"
)


func main() {
	accessToken := "YOUR_ACCESS_TOKEN"
	authenticator, err := accesstoken.Authenticator(accessToken)
	if err != nil {
		// handle error
	}
	client, err := sysdig.NewClient(authenticator)
}

The ibmiam subpackage authenticates each request with an IBM Cloud IAM Token. It automatically retrieves and refreshes an IAM Token using an IBM Cloud API Key.

package main

import (
	"context"
	"fmt"

	"github.com/trinchan/sysdig-go/sysdig"
	"github.com/trinchan/sysdig-go/sysdig/authentication/ibmiam"
)


func main() {
	apiKey := "YOUR_IBM_CLOUD_API_KEY"
	instanceID := "YOUR_IBM_CLOUD_MONITORING_INSTANCE_ID"
	authenticator, err := ibmiam.Authenticator(apiKey, ibmiam.WithIBMInstanceID(instanceID))
	if err != nil {
		// Handle error
	}
	client, err := sysdig.NewClient(authenticator, sysdig.WithIBMBaseURL(sysdig.RegionUSSouth, false))
}

See the example directory for more authentication examples.

Prometheus API

Sysdig offers a limited Prometheus HTTP API.

This API is exposed via the Prometheus Service of the Client. You can use this client to run PromQL queries against your Sysdig instance.

Most functionality of the HTTP API is not available from Sysdig, but they appear to be offering more and more. See the Prometheus example.

Client Options

Debug Mode

Debug mode can be enabled by setting the following client options:

sysdig.NewClient(sysdig.WithDebug(true), sysdig.WithLogger(log.Default())) // Or other Logger

Setting Debug mode will print out the request URLs and response body and headers, along with other debug information.

This is useful for debugging parse issues and during development.

Compression

The Sysdig API (and this client) supports gzip to reduce the size of responses. This can be useful for large queries.

sysdig.NewClient(sysdig.WithResponseCompression(true))

For other options, check the documentation.

FAQ

"Can you add X API?"

Yes! Open an issue with the API path and as much information about it as you can for a better chance of it getting developed. Or better yet, submit a patch!. In the mean time, you can also use the client.Do() method to send a custom request.

"The response for this API is wrong/broken!"

That's not a question! The client is incomplete as documentation for most of the Sysdig API has not been published. I have had to leave some types as interface{} until documentation is released or I receive a sample response. Submit an issue and include the (redacted) client logs with Debug mode enabled.

"The documentation is wrong!"

Since there is no official documentation for most of the API, some documentation is bound to be incorrect. Corrections and improvements are very welcome -- please file an issue or submit a patch if you find something is inaccurate.

"Is this an official client?"

Nope. The only official client I know is the Python SDK.

Versioning

sysdig-go is currently undergoing its initial development and is still incomplete. As new APIs are documented by Sysdig and IBM Cloud, new APIs will be added or changed. Since sysdig-go is a client library, breaking changes in the upstream API may require updates to the client. sysdig-go will follow semver as closely as possible to minimize breaking changes.

Credits

• Sysdig's Python SDK for API reference.
• Google's Github Client for client and repo design reference.

License

This library is distributed under the MIT license found in the LICENSE file.

---

"Sysdig" and "IBM Cloud" are registered trademarks of their respective holders. Use of the name does not imply any affiliation with or endorsement by them.