Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/runsidekick/sidekick-agent-nodejs

Nodejs agent for Sidekick open-source live application debugger
https://github.com/runsidekick/sidekick-agent-nodejs

debugging debugging-tool logging monitoring

Last synced: 3 months ago
JSON representation

Nodejs agent for Sidekick open-source live application debugger

Host: GitHub
URL: https://github.com/runsidekick/sidekick-agent-nodejs
Owner: runsidekick
License: agpl-3.0
Created: 2022-08-26T14:38:32.000Z (over 2 years ago)
Default Branch: master
Last Pushed: 2023-02-01T07:04:36.000Z (about 2 years ago)
Last Synced: 2024-10-31T17:29:58.102Z (3 months ago)
Topics: debugging, debugging-tool, logging, monitoring
Language: TypeScript
Homepage:
Size: 579 KB
Stars: 12
Watchers: 4
Forks: 2
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

Sidekick Node.js Agent

Sidekick Main Repository »

Table of Contents

What is Sidekick?
- Sidekick Actions

Sidekick Node.js Agent

Usage

Build the agent

Official Sidekick Agents

Resources

Questions? Problems? Suggestions?

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.](https://www.runsidekick.com/?utm_source=sidekick-nodejs-readme)

Learn More »

(back to top)

# Sidekick Node.js Agent

Sidekick Node.js agent allows you to inject tracepoints (non-breaking breakpoints) and logpoints dynamically to capture call stack snapshots (with variables) and add log messages on the fly without code modification, re-build and re-deploy. So it helps you, your team, and your organization to reduce MTTR (Minimum Time to Repair/Resolve).

To achieve this, Sidekick Node.js agent makes use of V8's inspector API.

The advantages of Sidekick over classical APM solutions is that, Sidekick

- can debug and trace any location (your code base or 3rd party dependency) in your application, not just the external (DB, API, etc ...) calls like APM solutions
- has zero overhead when you don't have any tracepoint or logpoint but APMs have always
- doesn't produce too much garbage data because it collects data only at the certain points you specified as long as that point (tracepoint/logpoint) is active

## Usage

```
npm install @runsidekick/sidekick-agent-nodejs
```

[Docs](https://docs.runsidekick.com/installation/installing-agents/node.js?utm_source=sidekick-nodejs-readme)

There are two way to integrate Sidekick agent to your application.

### Integrate Agent with Environment Variable

You can easily integrate Sidekick using below environment variables.

* set ``SIDEKICK_APIKEY`` environment variable with your Sidekick api key.
* set ``NODE_OPTIONS`` environment variable with `` '-r @runsidekick/sidekick-agent-nodejs/dist/bootstrap' ``

### Integrate Agent with Code

You can easily integrate Sidekick adding below code block to top of your project.

JS example
``` js
const SidekickDebugger = require('@runsidekick/sidekick-agent-nodejs');

SidekickDebugger.start({
apiKey: ''
});

...
```

TS example
``` ts
import * as SidekickDebugger from '@runsidekick/sidekick-agent-nodejs';

SidekickDebugger.start({
apiKey: ''
});

...

```

## Configs

| Config | Requirement | Environment Variable | Default
| --- | --- | --- | ---
| apiKey | Required | SIDEKICK_APIKEY | None
| logLevel | Optional | SIDEKICK_AGENT_LOG_LEVEL | info
| disable | Optional | SIDEKICK_AGENT_DISABLE | false
| brokerHost | Optional | SIDEKICK_AGENT_BROKER_HOST | Sidekick broker address
| brokerPort | Optional | SIDEKICK_AGENT_BROKER_PORT | Sidekick broker port
| brokerClient | Optional | SIDEKICK_AGENT_BROKER_CLIENT | Logged in user
| applicationId | Optional | SIDEKICK_AGENT_APPLICATION_ID | Generated by agent
| applicationName | Optional | SIDEKICK_AGENT_APPLICATION_NAME | Empty string
| applicationInstanceId | Optional | SIDEKICK_AGENT_APPLICATION_INSTANCE_ID | Generated by agent
| applicationVersion | Optional | SIDEKICK_AGENT_APPLICATION_VERSION | Empty string
| applicationStage | Optional | SIDEKICK_AGENT_APPLICATION_STAGE | Empty string
| applicationTag | Optional | SIDEKICK_AGENT_APPLICATION_TAG | None
| maxFrames | Optional | SIDEKICK_AGENT_MAX_FRAMES | 20
| maxExpandFrames | Optional | SIDEKICK_AGENT_MAX_EXPAND_FRAMES | 1
| maxProperties | Optional | SIDEKICK_AGENT_MAX_PROPERTIES | 10
| maxParseDepth | Optional | SIDEKICK_AGENT_MAX_PARSE_DEPTH | 3
| propertyAccessClassification | Optional | SIDEKICK_AGENT_PROPERTY_ACCESS_CLASSIFICATION | ENUMERABLE-OWN
| scriptPrefix | Optional | SIDEKICK_AGENT_SCRIPT_PREFIX | None
| rejectOnStartup | Optional | SIDEKICK_AGENT_REJECT_ON_STARTUP | false
| captureFrameDataReductionCallback | Optional | | None
| logMessageDataReductionCallback | Optional | | None
| errorCollectionEnable | Optional | SIDEKICK_AGENT_ERROR_COLLECTION_ENABLE | false
| errorCollectionEnableCaptureFrame | Optional | SIDEKICK_AGENT_ERROR_COLLECTION_CAPTURE_FRAME | false

### Valid Config Values

- `propertyAccessClassification` (`SIDEKICK_AGENT_PROPERTY_ACCESS_CLASSIFICATION`) configuration can take one of following values:
- `ENUMERABLE-OWN` (default value)
- `ENUMERABLE-OWN-AND-ENUMERABLE-PARENT`
- `ENUMERABLE-OWN-AND-NON-ENUMERABLE-OWN`
- `ENUMERABLE-OWN-AND-NON-ENUMERABLE-OWN-ENUMERABLE-PARENT`

## Build

- `npm run clean-build:all`

## Official Sidekick Agents

- [Java](https://github.com/runsidekick/sidekick-agent-java)
- [Node.js](https://github.com/runsidekick/sidekick-agent-nodejs)
- [Python](https://github.com/runsidekick/sidekick-agent-python)

## Resources:

- [Documentation](https://docs.runsidekick.com/?utm_source=sidekick-nodejs-readme)
- [Community](https://github.com/runsidekick/sidekick/discussions)
- [Discord](https://www.runsidekick.com/discord-invitation?utm_source=sidekick-nodejs-readme)
- [Contributing](https://github.com/runsidekick/sidekick/blob/master/CONTRIBUTING.md)
- [Sidekick Main Repository](https://github.com/runsidekick/sidekick)

## Questions? Problems? Suggestions?

To report a bug or request a feature, create a [GitHub Issue](https://github.com/runsidekick/sidekick-agent-nodejs/issues). Please ensure someone else has not created an issue for the same topic.

(back to top)

## Contact

[Reach out on the Discord](https://www.runsidekick.com/discord-invitation?utm_source=sidekick-nodejs-readme). A fellow community member or Sidekick engineer will be happy to help you out.

(back to top)