What is Sprkl?

Sprkl is a Personal Observability extension designed to help you write production-ready code faster and identify potential issues in your own code as soon as possible - when you write your code in the IDE. Powered by OpenTelemetry, we instrument every code change and analyze it upon execution. We then provide you with an immediate and personal feedback including:

• Personal code level traces - help you understand precisely how your recent code change executes.
• Personal Interactions - help you see how your code change plays with other entities in the system.
• Personal Coverage - helps you determine how much of your recent code change is covered by existing tests.
• Personal Insights - help you improve your code performance by getting runtime feedback.

You can watch a demo video here.

Install Sprkl to get…

• Your Personal Observability dashboard
• Traces histogram
• Errors
• Coverage
• Insights
• Interactions
• Jaeger-based instance traces
• Jest tests
• Code markups

Getting started

• Pre-requisites
• How to install Sprkl
• How to run Sprkl

About Sprkl

• Integrations and supported stack
• How it works
• FAQ

Install Sprkl to get…

Your Personal Observability dashboard 🦥

When the execution is complete, you will see your personalized information and insights in the Sprkl dashboard. The dashboard includes a number of areas filled with relevant information about your recent code change and its implications.

Traces histogram 👣

Every bar represents the number of traces in a given time. Note that it only shows traces relevant to your recent code change. If the bars are colored pink, it means there are errors in the traces (you can review them in the next section).

Errors ❗

See the errors resulting from your recent code change. When you click on an error message you will see the lines of code that initiated the error, and when you click on it, you will be redirected to those lines of code in the relevant file. Also, note the sloth icon next to some of the code lines. This icon tells you that Sprkl has information about this line and when you hover over the icon, you can select to see the latest trace that passed through this line or all the traces that passed through it. You can also click on the compass icon next to the code lines reference which will open a Jaeger instance in your IDE and allow you to follow a trace to better understand the error and its cause.

Coverage 🫶

The coverage section shows you what percentage of the statements that were added in your recent code change is covered by the tests you executed. It also shows you the specific lines of code that are covered or not covered. When you click on the lines of code, you are redirected to those lines in the relevant file. You can also click on the compass icon to follow the trace for the covered lines of code.

Insights ⚡

Insights are not necessarily errors but opportunities for you to identify certain areas in your recent code change that can be improved. It allows you to easily make sure that your code performs better and prevent certain issues from being pushed to production. When you click on an insight, you will see the lines of code that initiated the insight, and when you click on it you will be redirected to those lines of code in the relevant file. You can also click on the compass icon next to the code lines reference which will open a Jaeger instance in your IDE and allow you to follow a trace to better understand the insight.

Interactions 🔗

Interactions show you the ripple effect of your recent code change on the different system components. You can see details on HTTP requests including the relevant methods, database queries including the collections and methods, queues and other components. You can also see the details of your Jest tests execution including tests that passed through the recent code change and tests that didn’t, mocks, and assertions. When you click on an interaction message you will see the lines of code that initiated the interaction, and when you click on it you will be redirected to those lines of code in the relevant file. You can also click on the compass icon next to the code lines reference which will open a Jaeger instance in your IDE and allow you to follow a trace to better understand the interactions. Where relevant (HTTP, Mongo, etc.) you can also sort interaction messages by method, by clicking on the method.

Jaeger-based traces

Sprkl is leveraging Jaeger for visualizing and analyzing traces. You can easily open a trace from the Sprkl dashboard or from your code and it will automatically open in the relevant span (error, interaction, insight, etc.). Sprkl uniquely includes code level spans within the trace to show you not only the infrastructure level, but also how the trace passes through your recent code change. You can easily go back from the trace to the specific line of code by clicking on the sloth icon within the trace.

Jest tests

Sprkl natively supports Jest-based testing (unit and integration tests), with insights and traces for every execution. You can easily analyze failed tests, including details for mocks and assertions. Sprkl also shows you which specific tests passed through your recent code change.

Code markups

Sprkl allows you to easily switch between views so you can stay in context when analyzing the results. When you click on a code line reference in the Sprkl dashboard or inside a trace, Sprkl will automatically direct you to the relevant file and will highlight the specific line of code.

Getting started

Pre-requisites

• Supported OSs
  • Mac
  • Linux
  • WSL (for Windows machines). Information about running VSCode in WSL can be found here
• Node v16 and up
• Docker - you should have a docker set up on your machine, with permissions to run commands without a password. If you don’t have one, please use this link for information about setting it up
• VSCode installed
• A Node.Js application with git source control available on your local machine and can run locally. If you don’t have one you may use our demo repo.

How to install Sprkl

Once you install our app from the marketplace, you’ll need to sign up to get a token. Enter the token and the installation process will begin. It’s a 5 min setup. No further configuration is needed.

How to run Sprkl

In case you run your code directly on your machine - i.e. no docker, ssh, VM, etc. You can instrument your code changes by prefixing your commands with “sprkl –” (that is “sprkl dash dash”). For example:

Vanilla node

# Vanilla node
sprkl -- node index.js

NPM / Yarn

If you are running your code using package manager (npm / yarn):

# NPM
sprkl -- npm run <script-name>
sprkl -- npm run test
sprkl -- npm start

## Yarn
sprkl -- yarn run <script-name>
sprkl -- yarn run test

Startup script

If you are running your services with a startup script:

# Shell script
sprkl -- my_script.sh

Monorepo with NPM/Yarn scripts

# Monorepo with NPM start script
sprkl -- npm run <monorepo-startup-script-name>

# Monorepo with Yarn
sprkl -- yarn run <monorepo-startup-script-name>

Instrumenting Jest executions

In case you have Jest tests (unit tests or end-to-end) you can instrument them using sprkl like so:

# Jest test suite
sprkl -- jest
    
# Jest single test
sprkl -- jest my.test.js 
    
# Jest from from NPM script
sprkl -- npm run <jest-test-script-name>
    
# Jest from Yarn script
sprkl -- yarn run <jest-test-script-name>

Instrumenting containerized executions

If your code runs inside containers (docker or docker-compose) you can instrument it with sprkl

Docker

You can run your docker commands with sprkl like so:

# Docker image with default entrypoint
sprkl -- docker run my_image

# Docker image with non-default entrypoint:
sprkl -- docker run my_image node index.js

# Using docker cli arguments
sprkl -- docker run --rm -it my_image node index.js

Sprkl cli supports the full docker command syntax and you can use it as you would use any other docker command.

Docker compose

Sprkl can instrument docker-compose applications by changing the compose.yml file in-memory.

# Docker compose
sprkl -- docker compose up

If you wish to get the changed compose.yml file run the following:

# Getting the transformed compose.yml file
sprkl -- docker-compose-transform

About Sprkl

Integrations and supported stack

How it works

FAQ

• What is Sprkl?

  Sprkl is a Personal Observability platform that provides individual developers with telemetry data and actionable insights about their own code changes. We leverage OpenTelemetry to instrument every code change and analyze it upon execution. We then provide immediate feedback, right in the IDE, that includes traces at the code-level, not only at the infrastructure level (with an embedded Jaeger instance), insights about Jest tests, diff coverage, errors, hidden API calls, DB queries, performance bottlenecks, abnormal memory usage and more. You can read more here.

• How does Sprkl make my life easier?

  By using Sprkl, you immediately understand how your code performs. You no longer need to spend time manually collecting data and trying to piece it all together. No more sifting through endless logs or traces, adding breakpoints or switching from one tool to another. Sprkl helps you research, plan, debug, test and prevent issues, and investigate existing issues faster so you can focus on writing your best possible code. You can see a short demo right here.

• How does Sprkl work?

  We leverage OpenTelemetry to automatically instrument every code change and analyze it upon execution. See how it works in the illustration here.

• How do I “Git” started?

  Once you install our app from the marketplace, you’ll need to sign up to get a token. In the signup you’ll have a link to schedule a short kick-off meeting in which you’ll receive your token. Enter the token and the installation process will begin. It’s a 5 min. setup. No further configuration is needed.

• What languages does Sprkl support?

  We support TS, JS over Node.JS operating with the VSCode extension. We are gradually adding support for additional languages. Tell us what you’d like us to support here.

• Which Node.Js version does Sprkl support?

  Sprkl currently supports Node V.16 or higher

• How do I use Sprkl for TypeScript?

  Using Sprkl with TypeScript is as easy as using it for native Javascript. Just make sure that you enable sourcemaps when building the code, and that the sourcemaps are available when running Sprkl (either as files with the compiled code or inlined).

  Example using esbuild: esbuild

  --sourcemap …

  Example using tsc (tsconfig.json)

  {  
    "compilerOptions": {  
          ...  
          "sourceMap": true  
     },  
     ...  
  }
  

• Will my data be exposed or sent to external servers?

  No. Your data runs locally and will never be revealed.

• Does your instrumentation change my code?

  We don’t change your code’s functionality in any way. Instead, we add an instrumentation layer to your code that only runs on your local machine. We use our intelligent instrumentation engine to leverage OpenTelemetry (a typical, trustworthy open-source project) to automatically apply our instrumentation to your code.

• Does your instrumentation change my files?

  No. Sprkl doesn’t change your code functionality or files.

• Does Sprkl affect staging or production environments?

  No. Our code instrumentation is done locally, in memory, and not added to the source code. Therefore it doesn’t affect staging or production.

• Why don’t you instrument all the code?

  We focus on what you need to see to ship better code faster. Therefore, we focus on what’s relevant to your own code change - how it affects and is affected by system components. For example, your code-level traces, your hidden API calls, DB queries, messages, memory bottlenecks, diff coverage, errors, etc.

• Is there any performance overhead involved in using Sprkl?

  Local performance overhead is minimal as we instrument your code change alone, rather than the entire codebase. The instrumentation stays local and won’t apply to your files, and will not have any effect on staging or production.

• Will I be able to see Sprkl insights and telemetry data later in CI/CD, staging, or production?

  We’re working on it. We aim to show you how your code function changes throughout the entire lifecycle.

• Do I need to install Jaeger?

  No. It comes out of the box: you don’t need to deal with the hassle of installing it into your IDE.

• Can I see the instrumentation?

  No, unless you really want to :). We think it’s TMI and isn’t helpful. We want to help you focus on what matters.

• Can I configure what I want Sprkl to instrument?

  Of course. Sprkl can instrument any git recipe you can think of. For example, you can instrument or exclude: uncommitted changes, my commits only; all commits since I left the main branch; all commits in the last six months, etc. Those are configurable.

• How can I contribute?

  Got new feature suggestions or want to comment on existing ones? Connect with us here.

• Is Sprkl free?

  Yes, and it will always be free for an individual developer. However, we'd appreciate it if you spread the word amongst your fellow devs and communities that you engage in.