> For the complete documentation index, see [llms.txt](https://docs.blocktorch.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blocktorch.xyz/use-cases/managing-incidents/troubelshooting.md).

# Troubelshooting

At blocktorch we aim at being a reliable partner of our users throughout the whole software development lifecycle, and also equip engineers with the right tooling and data insights when troubleshooting. Below is an outline of steps that can be taken during the troubleshooting process and how blocktorch's toolkit can be of help during the process. Our mission is to help making web3 more reliable and secure for everyone involved. 

#### 1. Initial Assessment

* **Identify Symptoms**: Determine if the issue is a downtime or a security breach.
  * Building the relevant [monitors](/use-cases/monitoring.md) in blocktorch can be crucial in identifying systems as fast as possible. Blocktorch ships some [KPIs and visuals out of the box](/use-cases/dashboarding/pre-made-dashboards.md), which can help in identifying issues, but you know your software better than us, so building custom monitors is an important practice. From the charts you can directly navigate to the related logs by clicking the data points in the chart you need to investigate further
* **Scope of Impact**: Assess the extent—how many services, users, or systems are affected.
  * Looking at the[ stack traces and invocation flows](/use-cases/tracing.md) of the relevant logs can help figure out bottlenecks and affected services
  * We highly recommend also making use of [blocktorch's frontend Dragon SDK](/concepts/data-sources/react-frontends.md) to get deeper insights on client side issues 

#### 2. Communication

* **Notify Stakeholders**: Inform the relevant team members and stakeholders about the issue.
  * When your team members and stakeholders are[ part of your blocktorch project](/use-cases/collaborating/inviting-others.md), they can receive monitor alerts proactively
* **External Communication**: If necessary, prepare a communication plan for customers or the public.
  * Home dashboards as well as search queries are [shareable](/use-cases/collaborating/sharing-data.md) also with external stakeholders, so your community of users can get informed as well

#### 3. Isolation

* **Isolate Affected Systems**: To prevent further damage, isolate the compromised or malfunctioning components.
* **Limit Access**: Restrict access to sensitive systems until the nature and scope of the issue are understood.
  * you can disable functionalities in your UI
  * if your smart contracts are built with the functionality to pause functions, you can think of doing so

#### 4. Investigation

* **Review Logs**: Check application, security, and system logs for anomalies or indicators of the cause by utilizing [blocktorch's search](/use-cases/searching.md)
* **Identify Vulnerabilities**: Look for any vulnerabilities or errors that might have led to the issue.
  * Your smart contract code can be directly accessed in blocktorch's [contract details page](/concepts/data-sources/smart-contracts.md#smart-contract-details)
  * Blocktorch's [step debugger](/use-cases/debugging/step-debugger.md) can help you find the exact line of code causing the vulnerability or error
  * If your application is using Oracles and you believe the root cause could be there, you can check the Oracle's [out of the box details ](/concepts/data-sources/oracles.md#accessing-out-of-the-box-oracle-data)

#### 5. Mitigation

* **Patch and Update**: Apply necessary patches or updates to software to mitigate the vulnerability or error.
  * We are aware that this can be especially hard when the root cause lies within the smart contract, unless your project utilizes upgradable contract architecture
* **Make aware your users**: If a security breach is confirmed, prompt users to not sign any malicious smart contract interactions 

#### 6. Recovery

* **Restore Services**: Gradually restore services, ensuring they are fully sanitized and secure.
  * To test the services locally you can leverage blocktorch's [managed hardhat forks](/concepts/data-sources/local-forks/setup-managed-hardhat-fork.md)

#### 7. Postmortem Analysis

* **Analyze Causes**: Thoroughly document what happened, why it happened, and how it was resolved.
* **Review Processes**: Evaluate and update security policies, response strategies, and monitoring techniques to prevent future incidents.

#### 8. Ongoing Monitoring

* **Continuous Monitoring**: Implement additional custom real-time [monitoring](/use-cases/monitoring.md) in blocktorch to detect future issues promptly
* **Regular Audits**: Schedule regular security audits to ensure ongoing compliance and security.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.blocktorch.xyz/use-cases/managing-incidents/troubelshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.