Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

created debugging-harperdb.md file #117

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

created debugging-harperdb.md file #117

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 44 additions & 0 deletions docs/deployments/debugging-harperdb.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# Debugging HarperDB
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think somewhere up here we need to add some context around what kinds of debugging this is referring to. @kriszyp This information would be specifically for self-managed deployments, correct?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, this is for remote connection to servers that you have SSH access to and access to the ports.


If your HarperDB servers are experiencing performance issues, memory leaks, or errors, enabling debugging can help diagnose the problem. To start debugging, ensure that the HarperDB configuration has debugging enabled.

To learn more, please visit: [HarperDB Configuration - Threads](https://docs.harperdb.io/docs/deployments/configuration#threads)

In most deployments, debugging is already enabled. If it's set up, you can connect to HarperDB using Node DevTools, available via `chrome://inspect` in Chrome (click "Open dedicated DevTools for Node").
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would this be true in "most deployments" or is that referring to how we do our deployments? Not sure if this conflicts with what is in our config or not.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You are correct Jake, this is definitely not true for most deployments, it is only for our deployments, for our engineers.
In 4.4, with dev defaults on install, debug is enabled, but not with a starting port range, as is assumed in this doc.
If you are running inside a docker container, you have to enable a range of ports, which is somewhat of an elaborate process itself.


## Port Configuration for Debugging

Since DevTools can only connect to one thread per port, we assign specific ports for debugging:

- Main thread: Port 9229
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://docs.harperdb.io/docs/deployments/configuration#threads
This shows debug.port as 9249? Also it mentions startingPort, which is not in the sample config. Not sure if that's directly relevant to this, but seems like it.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should update those docs to be 9229, that is much more standard. But this should be clarified that this is connects to the ports configured in the starting port range.

- Worker 1: Port 9230
- Worker 2: Port 9231
- And so on for additional worker threads.

To debug multiple threads, you'll need to register each port in DevTools:

1. In the "Connections" tab, click "Add connection."
2. Add `localhost:9230`, `localhost:9231`, and any other necessary ports.
Comment on lines +16 to +21
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How would someone know how many threads they are using? Is there a way to get dev tools to connect to all threads without manually adding each connection?


## Connecting via SSH with Tunneling

When debugging a specific HarperDB instance, you’ll need to SSH into the instance using port tunneling. Here's how to connect to worker threads 1 and 2 (typically, debugging the main thread isn't needed since it doesn’t handle traffic):

```bash
ssh -L 9230:localhost:9230 -L 9231:localhost:9231 [email protected]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we'd want harperdbcloud.com examples in the public docs, but that may be my misunderstanding.

```

Once logged in, your DevTools should be able to connect to these threads for debugging.

## Debugging Tips

- Enable Pretty Printing: When debugging, be sure to enable pretty printing (bottom left of the code screen). This makes it easier to set breakpoints, even in HarperDB’s obfuscated code.

- Breakpoints in Application Code: If you're debugging your own application, just open the relevant file and set breakpoints as usual.


## Investigating Performance

- Run a Performance Profile: To investigate performance issues, start by running a profile for about 10-30 seconds. This will help you identify bottlenecks when analyzing the results.

- Check Memory Usage: For memory-related issues, take a heap snapshot to spot any large memory allocations. You can also compare heap usage over time to track memory growth or leaks.
Comment on lines +42 to +44
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Lets include some links here about how to analyze a performance profile or heap snapshot results.