<div align="center">
<a href="https://traceroot.ai/">
<img src="misc/images/banner.svg" alt="Banner" width="80%">
</a>
</div>
<div align="center">
[![Documentation][docs-image]][docs-url]
[![Discord][discord-image]][discord-url]
[![PyPI Version][pypi-image]][pypi-url]
[![PyPI SDK Downloads][pypi-sdk-downloads-image]][pypi-sdk-downloads-url]
[![TraceRoot.AI Website][company-website-image]][company-website-url]
[![X][company-x-image]][company-x-url]
[![LinkedIn][company-linkedin-image]][company-linkedin-url]
[![WhatsApp][company-whatsapp-image]][company-whatsapp-url]
</div>
<div align="center">
<h4 align="center">
[Contributing](CONTRIBUTING.md) |
[TraceRoot.AI](https://traceroot.ai/) |
[Community](https://discord.gg/CeuqGDQ58q/) |
[SDK](https://github.com/traceroot-ai/traceroot-sdk) |
[Documentation](https://docs.traceroot.ai)
</h4>
Join us ([*Discord*](https://discord.gg/CeuqGDQ58q/)) in pushing the boundaries of debugging with AI agents.
Please 🌟 Star TraceRoot on GitHub and be instantly notified of new releases.
</div>
## TraceRoot Framework Design Principles
<h3>🤖 Intelligence</h3 >
The framework enables multi-agent systems to continuously evolve by interacting with environments.
<h3>⏰ Real-Time</h3 >
The framework enables real-time tracing and logging to your applications.
<h3>🧠 Structured Information</h3 >
The framework enables utilizing structured loggings and tracing data to improve the performance of AI agents.
<h3>💻 Integration</h3 >
The framework enables integrating with other sources and tools, such as GitHub, Notion, etc. This provides a seamless experience for you to use the framework in your applications.
<h3>😊 Developer Friendly</h3 >
We provide a Cursor like interface but specialized for debugging and tracing. You can select the logs and traces you are interested in and ask the framework to help you with the analysis.
## Why Use TraceRoot for Your Applications?
We are a community-driven collective comprising over multiple engineers and researchers dedicated to advancing frontier engineering and research in using Multi-Agent Systems to help not only human but also AI agents on debugging, tracing, and root cause analysis.
<table style="width: 100%;">
<tr>
<td align="left">✅</td>
<td align="left" style="font-weight: bold;">Multi-Agent System</td>
<td align="left">Multi-Agent system that can be used to solve complex tasks.</td>
</tr>
<tr>
<td align="left">✅</td>
<td align="left" style="font-weight: bold;">Real-Time Tracing and Logging</td>
<td align="left">Enable real-time tracing and logging to your applications.</td>
</tr>
<tr>
<td align="left">✅</td>
<td align="left" style="font-weight: bold;">Structured Logging</td>
<td align="left">Enable structured logging to your applications, which allows better performance of AI agents.</td>
</tr>
<tr>
<td align="left">✅</td>
<td align="left" style="font-weight: bold;">Integration with Multiple Resources</td>
<td align="left">Integrate with other sources and tools, such as GitHub, Notion, etc.</td>
</tr>
<tr>
<td align="left">✅</td>
<td align="left" style="font-weight: bold;">Developer Friendly</td>
<td align="left">We provide a Cursor like interface but specialized for debugging and tracing.</td>
</tr>
</table>
## Installation
You can install the latest version of TraceRoot with the following command:
Or you can install the latest version of TraceRoot with the following command:
Install the dependencies locally:
```bash
python3.11 -m venv venv
source venv/bin/activate
pip install .
# Or
pip install -e .
```
## Local Usage
You can use the TraceRoot framework locally by following the [README.md in the `ui` directory](ui/README.md) and [README.md in the `rest` directory](rest/README.md).
Also, you can build the docker image and run the docker container by following the [README.md in the `docker` directory](docker/public/README.md).
Or even simpler, just pull the docker image by
```bash
docker pull zechengzh/traceroot-public:v0.0.1
docker run -d --name traceroot-public -p 3000:3000 -p 8000:8000 zechengzh/traceroot-public:v0.0.1
```
This will start the UI at [http://localhost:3000](http://localhost:3000) and the API at [http://localhost:8000](http://localhost:8000).
Before using the TraceRoot framework, you need to setup the Jaeger docker container at first. It will be used to store the traces and logs and capture the traces and logs from our SDK integrated with your applications.
```bash
docker run -d --name jaeger \
-e COLLECTOR_OTLP_ENABLED=true \
-p 16686:16686 \
-p 14268:14268 \
-p 14250:14250 \
-p 4317:4317 \
-p 4318:4318 \
cr.jaegertracing.io/jaegertracing/jaeger:2.8.0
```
## SDK
Our platform is built on top of the TraceRoot SDK. You need to use our SDK to integrate with your applications by
```bash
pip install traceroot==0.0.4a5
```
To use the local mode of the TraceRoot SDK, you need create a `.traceroot-config.yaml` file in the root directory of your project with following content:
```yaml
local_mode: true
service_name: "your-service-name"
github_owner: "your-github-owner"
github_repo_name: "your-github-repo-name"
github_commit_hash: "your-github-commit-hash"
```
As mentioned above, you need to setup the Jaeger docker container at first before let the TraceRoot SDK capture the traces and logs from your applications.
For more details or the SDK usage and examples, please checkout this [Quickstart](https://docs.traceroot.ai/quickstart).
[docs-image]: https://img.shields.io/badge/Documentation-0dbf43
[docs-url]: https://docs.traceroot.ai
[discord-url]: https://discord.gg/CeuqGDQ58q/
[discord-image]: https://img.shields.io/discord/1395844148568920114?logo=discord&labelColor=%235462eb&logoColor=%23f5f5f5&color=%235462eb
[pypi-image]: https://badge.fury.io/py/traceroot.svg
[pypi-url]: https://pypi.python.org/pypi/traceroot
[company-website-image]: https://img.shields.io/badge/TraceRoot.AI-148740
[company-website-url]: https://traceroot.ai
[company-x-url]: https://x.com/TracerootAI
[company-x-image]: https://img.shields.io/twitter/follow/TracerootAI?style=social
[company-linkedin-url]: https://www.linkedin.com/company/traceroot-ai/
[company-linkedin-image]: https://custom-icon-badges.demolab.com/badge/LinkedIn-0A66C2?logo=linkedin-white&logoColor=fff
[company-whatsapp-url]: https://chat.whatsapp.com/GzBii194psf925AEBztMir
[company-whatsapp-image]: https://img.shields.io/badge/WhatsApp-25D366?logo=whatsapp&logoColor=white
[pypi-sdk-downloads-image]: https://img.shields.io/pypi/dm/traceroot
[pypi-sdk-downloads-url]: https://pypi.python.org/pypi/traceroot
Raw data
{
"_id": null,
"home_page": null,
"name": "traceroot-framework",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "opentelemetry, agents, dev, del-tools, artificial-intelligence, tracing, logging, debugging, rest-api, multi-agent-systems, coding, debugging-assistant",
"author": "Zecheng Zhang, Xinwei He",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/9d/94/c938bd1c47c90057e17df78b59346eab55589a7073635a9e708aeb35248d/traceroot_framework-0.0.1.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <a href=\"https://traceroot.ai/\">\n <img src=\"misc/images/banner.svg\" alt=\"Banner\" width=\"80%\">\n </a>\n</div>\n\n<div align=\"center\">\n\n[![Documentation][docs-image]][docs-url]\n[![Discord][discord-image]][discord-url]\n[![PyPI Version][pypi-image]][pypi-url]\n[![PyPI SDK Downloads][pypi-sdk-downloads-image]][pypi-sdk-downloads-url]\n[![TraceRoot.AI Website][company-website-image]][company-website-url]\n[![X][company-x-image]][company-x-url]\n[![LinkedIn][company-linkedin-image]][company-linkedin-url]\n[![WhatsApp][company-whatsapp-image]][company-whatsapp-url]\n\n</div>\n\n\n<div align=\"center\">\n<h4 align=\"center\">\n\n[Contributing](CONTRIBUTING.md) |\n[TraceRoot.AI](https://traceroot.ai/) |\n[Community](https://discord.gg/CeuqGDQ58q/) |\n[SDK](https://github.com/traceroot-ai/traceroot-sdk) |\n[Documentation](https://docs.traceroot.ai)\n\n</h4>\n\nJoin us ([*Discord*](https://discord.gg/CeuqGDQ58q/)) in pushing the boundaries of debugging with AI agents. \n\nPlease \ud83c\udf1f Star TraceRoot on GitHub and be instantly notified of new releases.\n</div>\n\n## TraceRoot Framework Design Principles\n\n<h3>\ud83e\udd16 Intelligence</h3 >\n\nThe framework enables multi-agent systems to continuously evolve by interacting with environments.\n\n<h3>\u23f0 Real-Time</h3 >\n\nThe framework enables real-time tracing and logging to your applications.\n\n<h3>\ud83e\udde0 Structured Information</h3 >\n\nThe framework enables utilizing structured loggings and tracing data to improve the performance of AI agents.\n\n<h3>\ud83d\udcbb Integration</h3 >\n\nThe framework enables integrating with other sources and tools, such as GitHub, Notion, etc. This provides a seamless experience for you to use the framework in your applications.\n\n<h3>\ud83d\ude0a Developer Friendly</h3 >\n\nWe provide a Cursor like interface but specialized for debugging and tracing. You can select the logs and traces you are interested in and ask the framework to help you with the analysis.\n\n## Why Use TraceRoot for Your Applications?\n\nWe are a community-driven collective comprising over multiple engineers and researchers dedicated to advancing frontier engineering and research in using Multi-Agent Systems to help not only human but also AI agents on debugging, tracing, and root cause analysis.\n\n<table style=\"width: 100%;\">\n\n <tr>\n <td align=\"left\">\u2705</td>\n <td align=\"left\" style=\"font-weight: bold;\">Multi-Agent System</td>\n <td align=\"left\">Multi-Agent system that can be used to solve complex tasks.</td>\n </tr>\n <tr>\n <td align=\"left\">\u2705</td>\n <td align=\"left\" style=\"font-weight: bold;\">Real-Time Tracing and Logging</td>\n <td align=\"left\">Enable real-time tracing and logging to your applications.</td>\n </tr>\n <tr>\n <td align=\"left\">\u2705</td>\n <td align=\"left\" style=\"font-weight: bold;\">Structured Logging</td>\n <td align=\"left\">Enable structured logging to your applications, which allows better performance of AI agents.</td>\n </tr>\n <tr>\n <td align=\"left\">\u2705</td>\n <td align=\"left\" style=\"font-weight: bold;\">Integration with Multiple Resources</td>\n <td align=\"left\">Integrate with other sources and tools, such as GitHub, Notion, etc.</td>\n </tr>\n <tr>\n <td align=\"left\">\u2705</td>\n <td align=\"left\" style=\"font-weight: bold;\">Developer Friendly</td>\n <td align=\"left\">We provide a Cursor like interface but specialized for debugging and tracing.</td>\n </tr>\n</table>\n\n## Installation\n\nYou can install the latest version of TraceRoot with the following command:\n\nOr you can install the latest version of TraceRoot with the following command:\n\nInstall the dependencies locally:\n\n```bash\npython3.11 -m venv venv\nsource venv/bin/activate\npip install .\n# Or\npip install -e .\n```\n\n## Local Usage\n\nYou can use the TraceRoot framework locally by following the [README.md in the `ui` directory](ui/README.md) and [README.md in the `rest` directory](rest/README.md).\n\nAlso, you can build the docker image and run the docker container by following the [README.md in the `docker` directory](docker/public/README.md).\n\nOr even simpler, just pull the docker image by\n\n```bash\ndocker pull zechengzh/traceroot-public:v0.0.1\ndocker run -d --name traceroot-public -p 3000:3000 -p 8000:8000 zechengzh/traceroot-public:v0.0.1\n```\n\nThis will start the UI at [http://localhost:3000](http://localhost:3000) and the API at [http://localhost:8000](http://localhost:8000).\n\nBefore using the TraceRoot framework, you need to setup the Jaeger docker container at first. It will be used to store the traces and logs and capture the traces and logs from our SDK integrated with your applications.\n\n```bash\ndocker run -d --name jaeger \\\n -e COLLECTOR_OTLP_ENABLED=true \\\n -p 16686:16686 \\\n -p 14268:14268 \\\n -p 14250:14250 \\\n -p 4317:4317 \\\n -p 4318:4318 \\\n cr.jaegertracing.io/jaegertracing/jaeger:2.8.0\n```\n\n## SDK\n\nOur platform is built on top of the TraceRoot SDK. You need to use our SDK to integrate with your applications by\n\n```bash\npip install traceroot==0.0.4a5\n```\n\nTo use the local mode of the TraceRoot SDK, you need create a `.traceroot-config.yaml` file in the root directory of your project with following content:\n```yaml\nlocal_mode: true\nservice_name: \"your-service-name\"\ngithub_owner: \"your-github-owner\"\ngithub_repo_name: \"your-github-repo-name\"\ngithub_commit_hash: \"your-github-commit-hash\"\n```\n\nAs mentioned above, you need to setup the Jaeger docker container at first before let the TraceRoot SDK capture the traces and logs from your applications.\n\nFor more details or the SDK usage and examples, please checkout this [Quickstart](https://docs.traceroot.ai/quickstart).\n\n[docs-image]: https://img.shields.io/badge/Documentation-0dbf43\n[docs-url]: https://docs.traceroot.ai\n[discord-url]: https://discord.gg/CeuqGDQ58q/\n[discord-image]: https://img.shields.io/discord/1395844148568920114?logo=discord&labelColor=%235462eb&logoColor=%23f5f5f5&color=%235462eb\n[pypi-image]: https://badge.fury.io/py/traceroot.svg\n[pypi-url]: https://pypi.python.org/pypi/traceroot\n[company-website-image]: https://img.shields.io/badge/TraceRoot.AI-148740\n[company-website-url]: https://traceroot.ai\n[company-x-url]: https://x.com/TracerootAI\n[company-x-image]: https://img.shields.io/twitter/follow/TracerootAI?style=social\n[company-linkedin-url]: https://www.linkedin.com/company/traceroot-ai/\n[company-linkedin-image]: https://custom-icon-badges.demolab.com/badge/LinkedIn-0A66C2?logo=linkedin-white&logoColor=fff\n[company-whatsapp-url]: https://chat.whatsapp.com/GzBii194psf925AEBztMir\n[company-whatsapp-image]: https://img.shields.io/badge/WhatsApp-25D366?logo=whatsapp&logoColor=white\n[pypi-sdk-downloads-image]: https://img.shields.io/pypi/dm/traceroot\n[pypi-sdk-downloads-url]: https://pypi.python.org/pypi/traceroot\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "TraceRoot - Comprehensive AI-powered tracing, monitoring and REST API solution",
"version": "0.0.1",
"project_urls": {
"Bug Reports": "https://github.com/traceroot-ai/traceroot/issues",
"Documentation": "https://github.com/traceroot-ai/traceroot#readme",
"Homepage": "https://github.com/traceroot-ai/traceroot",
"Repository": "https://github.com/traceroot-ai/traceroot"
},
"split_keywords": [
"opentelemetry",
" agents",
" dev",
" del-tools",
" artificial-intelligence",
" tracing",
" logging",
" debugging",
" rest-api",
" multi-agent-systems",
" coding",
" debugging-assistant"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "be189e0ae8375c4577f6c0edc0f4156b503a02cbccf1bb2e918b970676ed9165",
"md5": "10579fbd71dac04a78f5de4714090a23",
"sha256": "cca30c43a2771885974dc7bc14dae4e82e78e049bef600619aa6a78f4585462e"
},
"downloads": -1,
"filename": "traceroot_framework-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "10579fbd71dac04a78f5de4714090a23",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 62927,
"upload_time": "2025-07-23T18:52:43",
"upload_time_iso_8601": "2025-07-23T18:52:43.706835Z",
"url": "https://files.pythonhosted.org/packages/be/18/9e0ae8375c4577f6c0edc0f4156b503a02cbccf1bb2e918b970676ed9165/traceroot_framework-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9d94c938bd1c47c90057e17df78b59346eab55589a7073635a9e708aeb35248d",
"md5": "efd1e893fb3e5a87fda552024c33b755",
"sha256": "6f60730282f649e1ebf8abae2b6dc63a96c5fbadb1aaf7870da8e43b090f5a42"
},
"downloads": -1,
"filename": "traceroot_framework-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "efd1e893fb3e5a87fda552024c33b755",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 50606,
"upload_time": "2025-07-23T18:52:45",
"upload_time_iso_8601": "2025-07-23T18:52:45.289924Z",
"url": "https://files.pythonhosted.org/packages/9d/94/c938bd1c47c90057e17df78b59346eab55589a7073635a9e708aeb35248d/traceroot_framework-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-23 18:52:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "traceroot-ai",
"github_project": "traceroot",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "traceroot-framework"
}
JSON
