sidekick

       

Table of Contents

1. What is Sidekick?
   • Sidekick Actions
2. Why Sidekick?
3. Features
4. Who should use Sidekick?
5. How does Sidekick work?
6. Getting Started
   • Running Sidekick using our Docker image
   • Building Sidekick
7. Sidekick Ecosystem
   • Documentation
   • Agents
   • Clients
   • Usage Examples
   • Sidekick Recipes
   • Recent Publications
8. Contributing
9. Questions? Problems? Suggestions?
10. Contact

What is Sidekick?

Sidekick is a live application debugger that lets you troubleshoot your applications while they keep on running.

Add dynamic logs and put non-breaking breakpoints in your running application without the need of stopping & redeploying.

Sidekick Open Source is here to allow self-hosting and make live debugging more accessible. Built for everyone who needs extra information from their running applications.

Sidekick Actions:

Sidekick has two major actions; Tracepoints & Logpoints.

• A tracepoint is a non-breaking remote breakpoint. In short, it takes a snapshot of the variables when the code hits that line.
• Logpoints open the way for dynamic(on-demand) logging to Sidekick users. Replacing traditional logging with dynamic logging has the potential to lower stage sizes, costs, and time for log searching while adding the ability to add new logpoints without editing the source code, redeploying, or restarting the application.

Supported runtimes: Java, Python, Node.js

To learn more about Sidekick features and capabilities, see our web page.

(back to top)

Why Sidekick?

You can use Sidekick in any stage of your development for your live debugging & logging needs. With Sidekick you can:

• Debug your remote application (monoliths or microservices on Kubernetes, Docker, VMs, or Local) and collect actionable data from your remote application.
• Add logs to your production apps without redeploying or restarting
• Cut your monitoring costs with on-demand & conditional logpoints & tracepoints
• On-board new developers by showing how your apps work using real-time data.
• Observe Event-Driven Systems with ease
• Programmatically control where and when you collect data from your applications
• Either use Sidekick’s Web IDE, VS Code & IntelliJ IDEA extensions to control your Sidekick Actions or use headless clients to bring Sidekick to your workflow in any way you want!
• Evaluate the impact of an error on applications with integrated distributed tracing.
• Collaborate with your colleagues by sharing snapshots taken by Sidekick.
• Reduce the time spent context-switching between different tools.

All these with almost no overhead. PS: Check out our benchmark blogs

(back to top)

Features

• Conditions & custom hit limits for your logpoints and tracepoints -> collect only what you need
• Mustache powered expression system for logpoints -> easily add variable data to your logs context
• Customizable agents -> configure how your agents work, define depth and frame numbers
• Aggregate your collected data with Thundra APM and Open-telemetry traces
• Collect errors automatically and send them to your target of choice
• Define custom data redaction functions to control what is being collected
• Control your logpoints and tracepoints using client libraries & REST API
• Work with your collected data in your way using Sidekick clients

(back to top)

Who should use Sidekick?

While utilizing log data seems the most obvious choice for debugging a remote application, Sidekick provides an extra edge with a seamless debugging experience that is similar to debugging an application on your local environment.

*you*

Whether you’re a developer, testing software engineer, or QA engineer, Sidekick is here to help you find the root cause of the errors.

(back to top)

How does Sidekick work?

Sidekick consists of 3 layers;
The broker is the central unit of Sidekick. It controls all the data flow between clients and agents. This very repository contains the Sidekick broker.

Agents are the layer where Sidekick actions meet with your applications. Agents deployed with your software lets you collect snapshot data and generate dynamic logs without modifying your code. Agents get orders from clients and start listening to the targeted lines with given properties. Then whenever your code hits a logpoint or a tracepoint, agents collect stack & log data and send them to the clients via the broker. Currently, we have agents for Java, Python & Node.js runtimes.

Clients let you interact with the agents. They send commands to agents via the broker and let you control your tracepoints & logpoints. Clients come in many different ways:

• The first one is Sidekick Web IDE, which you can use with our SaaS & on-prem versions, it lets you collaborate with other developers, and control your agents, workspaces & users from your browser. Since it is a web app, it does not require any installation. To learn more about Sidekick SaaS & On-prem features and capabilities, see our web page.
• Secondly, we have our IDE extensions. They enable you to control your agents with the comfort of your IDE. Currently, we have extensions for Visual Studio Code & IntelliJ IDEA. Check out the Clients section below.
• Last but not least, you can also use Sidekick with a headless approach. Sidekick Rest API lets you apply CRUD operations over logpoints & tracepoints via HTTP protocol and other clients like Sidekick Node.js Client lets you control your agents programmatically and make use of your collected data using code.

(back to top)

Getting Started

The simplest way to use Sidekick is to create an account on Sidekick Cloud. For the self-hosted version, you can either build Sidekick yourself or use our Docker image.

Note
Make sure docker daemon is running.

Running Sidekick using our Docker image

Note
Docker images are not supported on ARM64 machines. Follow building instructions to run Sidekick on your machine or visit http://www.runsidekick.com for the cloud hosted version

1. Configure Environment Variables

   1. Go to the docker folder under the project
   2. Open .env file via any text editor
      1. Set your secret token (you can set any value, this will be your master key)
         1. API_TOKEN, BROKER_CLIENT_AUTHTOKEN and BROKER_TOKEN must be the same, otherwise, you can’t connect your apps and your client
      2. Set MySQL secrets
         1. Set MySQL root password (MYSQL_ROOT_PASSWORD)
         2. Set MySQL user (MYSQL_USER, SPRING_DATASOURCE_USERNAME)
         3. Set MySQL password (MYSQL_PASSWORD, SPRING_DATASOURCE_PASSWORD)

2. Running Application Stack

   • Go to the docker folder under the project

   • Run command docker-compose up -d and wait for a minute

   • App is ready

   • You can connect to the broker using the url

     ws://<your-server-hostname-or-ip>:7777

   • You can see the API’s swagger interface at

     http://<your-server-hostname-or-ip>:8084/swagger-ui/index.html

Building Sidekick

Note
Follow Build Service Images (Advanced) for arm64 builds

1. Build Service Images (Basic)

   1. Build Sidekick Broker Image

      1. Go to sidekick/sidekick-broker-app folder under project
      2. Execute release.sh

   2. Build Sidekick API Image

      1. Go to sidekick/sidekick-api folder under project
      2. Execute release.sh

2. Build Service Images (Advanced)

   1. Go to main project folder
   2. Run command mvn clean install -DskipTests=true
   3. Go to sidekick-api folder cd sidekick-api
   4. Build API image docker build --build-arg JAR_FILE=target/sidekick-api.jar -t runsidekick/sidekick-api:latest .
   5. Go to sidekick-broker-app folder cd ../sidekick-broker/sidekick-broker-app
   6. Build Broker image docker build --build-arg JAR_FILE=target/sidekick-broker-app.jar -t runsidekick/sidekick-broker:latest .
   7. Run docker-compose up -d under docker folder

Now that your broker is ready, you need to install your agents & clients to start using Sidekick. Check out them below.

To learn more see our docs.

(back to top)

Sidekick Ecosystem

Documentation

• Sidekick Docs

• Thundra APM & Open-telemetry Integration

• Node.js Data redaction

(back to top)

Agents

Check out docs to learn how you can use agents with Sidekick Open Source!

• Sidekick Java Agent:

  • Docs

  • Repository

• Sidekick Python Agent:

  • Docs

  • Repository

• Sidekick Node.js Agent:

  • Docs

  • Repository

(back to top)

Clients

Check out docs to learn how you can use clients with Sidekick Open Source!

• VSCode Extension (Python & Node.js):

  • Extension Page

  • Docs Page

• IntelliJ IDEA (Java):

  • Plugin Page

  • Docs Page

• PyCharm (Python):

  • Plugin Page

  • Docs Page

• WebStorm (Node.js):

  • Plugin Page

  • Docs Page

• Sidekick Node.js Client:

  Sidekick Node Client opens up a new & headless way to use Sidekick. It allows you to both use custom ingest functions for the tracepoint or logpoint events and put/edit/delete your tracepoints/logpoints easily using code.

  Note
  This can be used with agents from all runtimes.

• REST API

  Sidekick REST API Doc

(back to top)

Usage Examples

• Collect Realtime Stack Traces from NodeJS Applications

• How to add missing logpoints to your running applicatons without stopping and send them to Loki

• Capturing Exception Call Stacks from Node.js Applications

• Achieving Rule-based observability using Sidekick and Camunda

• Embed Sidekick features to your applications

Check out docs for more!

(back to top)

Sidekick Recipes

1. Ingest your Sidekick logs & snapshots to Loki. https://github.com/boroskoyo/sidekick-loki

   Related blog post: Sidekick Recipes #2: Send logs to Loki -Add missing logs to your running microservices. Easy as 1–2–3

2. Send your collected tracepoint & logpoint events to Elasticsearch https://github.com/boroskoyo/sidekick-elastic

   Related blog post: Sidekick Recipes #1: Elasticsearch Ingest

(back to top)

Recent Publications

• Sidekick Open Source Live Debugger : Get started in 5 mins
• Past, Present, and Future of Sidekick
• Production Debuggers — 2022 Benchmark Results
• Bringing the simplicity of print() to production debugging using PyCharm

(back to top)

Contributing

Checkout CONTRIBUTING.md

(back to top)

Questions? Problems? Suggestions?

To report a bug or request a feature, create a GitHub Issue. Please ensure someone else has not created an issue for the same topic.

(back to top)

Contact

Reach out on the Discord. A fellow community member or Sidekick engineer will be happy to help you out.

(back to top)