{"id":26267483,"url":"https://github.com/oslabs-beta/tuba","last_synced_at":"2025-04-30T19:08:43.358Z","repository":{"id":226971018,"uuid":"769711037","full_name":"oslabs-beta/Tuba","owner":"oslabs-beta","description":"Tuba traces, parses, and stores errors across all microservices and offers an intuitive interface with comprehensive features designed to streamline error detection, diagnosis, and resolution.","archived":false,"fork":false,"pushed_at":"2024-05-18T21:43:56.000Z","size":1477,"stargazers_count":19,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-30T19:07:59.583Z","etag":null,"topics":["errors","express","expressjs","microservice","microservices","microservices-architecture","nodejs","postgresql","prometheus"],"latest_commit_sha":null,"homepage":"https://tuba-tracing.dev/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oslabs-beta.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"open-source-labs","custom":["https://donorbox.org/donations-to-oslabs-inc"]}},"created_at":"2024-03-09T20:51:37.000Z","updated_at":"2025-01-21T17:17:12.000Z","dependencies_parsed_at":"2024-04-21T18:47:54.777Z","dependency_job_id":"f5d381c0-0ddc-4026-bcee-80511f54499b","html_url":"https://github.com/oslabs-beta/Tuba","commit_stats":null,"previous_names":["oslabs-beta/tuba"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oslabs-beta%2FTuba","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oslabs-beta%2FTuba/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oslabs-beta%2FTuba/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oslabs-beta%2FTuba/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oslabs-beta","download_url":"https://codeload.github.com/oslabs-beta/Tuba/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251767187,"owners_count":21640469,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["errors","express","expressjs","microservice","microservices","microservices-architecture","nodejs","postgresql","prometheus"],"created_at":"2025-03-14T04:17:01.353Z","updated_at":"2025-04-30T19:08:43.334Z","avatar_url":"https://github.com/oslabs-beta.png","language":"JavaScript","funding_links":["https://github.com/sponsors/open-source-labs","https://donorbox.org/donations-to-oslabs-inc"],"categories":[],"sub_categories":[],"readme":"# TUBA\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"250px\" src=\"./src/Images/TubaLogo.png\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Trace and log runtime errors through a microservices application.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/react-%2320232a.svg?style=for-the-badge\u0026logo=react\u0026logoColor=%2361DAFB\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/redux-764abc.svg?style=for-the-badge\u0026logo=redux\u0026logoColor=white\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/node.js-6DA55F?style=for-the-badge\u0026logo=node.js\u0026logoColor=white\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/express.js-%23404d59.svg?style=for-the-badge\u0026logo=express\u0026logoColor=%2361DAFB\" /\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/docker-2153a3.svg?style=for-the-badge\u0026logo=docker\u0026logoColor=white\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/prometheus-e6522c?style=for-the-badge\u0026logo=prometheus\u0026logoColor=white\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/-jest-%23C21325?style=for-the-badge\u0026logo=jest\u0026logoColor=white\" /\u003e\n\u003c/p\u003e\n\n---\n### Features\n\nTUBA is an error parsing package for Express.js and Docker image that work together, allowing you to quickly review and interpret error data in each service over a given range of time.\n\n**Own Your Data**\n\nHave full control of mission-critical historical runtime data in a postgres database you manage.\n\n**Don't Get Lost in the Cloud**\n\nUse the TUBA Interface to visualize your error data in chronological order, highlight any cascades or closely related errors on your Timeline. Review your Heatmap to see errors by service, or search and filter data by keywords. \n\n**Native Prometheus Integration**\n\nTUBA comes with a suite of custom Prometheus metrics that integrate seamlessly into your existing Prometheus implementation and metrics visualizer.\n\n---\n## How to use TUBA\n### Express.js\n\nFor each individual service in your microservice architecture, include the package in your dependencies:\n\n```Bash\nnpm i tuba-tracing\n```\n\nNow you’re ready to require the package function into the file where Express does your error handling:\n\n```JavaScript\nconst { tubaMetricRouter } = require('tuba-tracing');\n```\n\nThe function should be invoked in the Express global error handler, and passed the JavaScript error object and the name of the service/app in which the error occurred:\n\n```JavaScript\n// Global Error handler\napp.use((err, req, res, next) =\u003e {\n\n  // TUBA error metrics and parsing\n  tubaMetricRouter(err, 'the name of your service');\n\n  // Your custom error handling for http response\n  res.status(500).json({\"message\": \"An error occurred!\"});\n});\n```\nYou will need to setup/provide your own secure postgres Database. This ensures your data is secure and private.\nCreate an empty database and place the URI in an .env file. You MUST use TUBA_PG_URI as the proprety key. Ex:\n\n```bash\nTUBA_PG_URI='https://postgress.database.link.here.com'\n```\nTuba now has access to your database. The database schema should still be unconfigured at this point. This can be done via a simple Postman request that will be covered in the Docker Image section of the docs.\n\n## Prometheus\n\nIf you are using Tuba in a Prometheus environment, you can take advantage of the custom Prometheus metrics included in the npm package. \n\nTo use this functionality, include the prom-client package in your dependencies:\n\n```bash\nnpm i prom-client\n```\nThen require the dependency in your server routing file:\n\n```JavaScript\nconst promClient = require('prom-client');\n```\nExpose `/metrics` in your Express routing to allow Prometheus to scrape the data that TUBA will capture:\n\n```JavaScript\n// Expose metrics endpoint for Prometheus to scrape\napp.get('/metrics', async (req, res) =\u003e {\n  res.set('Content-Type', promClient.register.contentType);\n  res.send( await promClient.register.metrics());\n});\n```\nFor instructions on how to set up prometheus, see the [Prometheus documentation](/https://prometheus.io/).\n\n## Docker\n\nThis repo is an exact mirror of the code that runs inside the official TUBA image, and can be run independently as a full-stack application with all the functionality and features of the Docker image. The Tuba interface is run via this Docker image.\n\nThe Tuba Docker image can run independently as a standalone container or alongside your microservices images in you application's pre-configured container.\n\nThe TUBA Docker image can be downloaded with Docker Desktop or from Docker Hub with this terminal command:\n\n```Bash\ndocker pull tubatracing/tuba-tracing:latest\n```\n\nIf you are running Tuba as a standalone container, you’ll need to pass in the link to your postgres database when you start up the image container: \n\n```Bash\ndocker run -p [Your Port]:42069 -e TUBA_PG_URI=[Your URI] tubatracing/tuba-tracing:latest\n```\nNavigte to localhost:[Your Port] to use TUBA\n\n## Microserviced Environment\nTo use Tuba alongside other images with `docker-compose`, you can add the Docker Hub Tuba image to your `docker-compose` file:\nThe Tuba image in the below example references a `.env` file that should have the same key value as detailed in the npm package section of these docs:\n\n```YAML\nversion: \"3\"\nservices:\n  tuba:\n    image: tubatracing/tuba-tracing:latest\n    env_file:\n      - .env\n    ports:\n      - \"[YOUR PORT]:42069\"\n  your-other-service:\n    build:\n      context: ./path/to/your/service\n      dockerfile: Dockerfile-your-service\n    networks:\n      - localnetwork\n    ports:\n      - 3000:3000\n```\n\n## Database Instantiation\n\nThe first time you start the TUBA image, the interface should be visible but will stall on the loading screen \"Fetching Errors from Database.\" This is because the database schema hasn't been set yet. To do this, make sure the image is running and send a `GET` request to `http://localhost:[YOUR PORT]/setup/`. Doing so will run this SQL script in your database to create the necessary tables and columns:\n\n```SQL\nCREATE TABLE users (\nusr_id SERIAL PRIMARY KEY,\nusr_name VARCHAR(250) NOT NULL,\nusr_password VARCHAR(1000) NOT NULL,\nusr_email VARCHAR(500) NOT NULL\n);\nCREATE TABLE applications (\napp_id SERIAL PRIMARY KEY,\napp_usr_id INTEGER REFERENCES users (usr_id) NOT NULL,\napp_name VARCHAR(500) NOT NULL,\napp_kubernetes BOOLEAN NOT NULL\n);\nCREATE TABLE services (\nsrv_id SERIAL PRIMARY KEY,\nsrv_name VARCHAR(500) NOT NULL,\nsrv_language VARCHAR(250),\nsrv_usr_id INTEGER REFERENCES users (usr_id) NOT NULL,\nsrv_app_id INTEGER REFERENCES applications (app_id) NOT NULL\n);\nCREATE TABLE error_data (\nerr_id SERIAL PRIMARY KEY,\nerr_app_id INTEGER REFERENCES applications (app_id) NOT NULL,\nerr_srv_id INTEGER REFERENCES services (srv_id) NOT NULL,\nerr_job_name VARCHAR(500) NOT NULL,\nerr_time BIGINT NOT NULL,\nerr_message VARCHAR(1000),\nerr_type VARCHAR(250) NOT NULL,\nerr_stack VARCHAR(4000) NOT NULL,\nerr_file_path VARCHAR(2000),\nerr_file VARCHAR(500),\nerr_line_num INTEGER,\nerr_module VARCHAR(500),\nerr_module_function VARCHAR(500),\nerr_full_text VARCHAR(2000)\n);\nCREATE TABLE service_connections (\ncon_id SERIAL PRIMARY KEY,   \ncon_srv1 INTEGER REFERENCES services (srv_id) NOT NULL,\ncon_srv2 INTEGER REFERENCES services (srv_id) NOT NULL\n);\n```\n\nYou will then need to populate the following tables with the relevant data that is unique to your application:\n* users\n* applications \n* services \n* service_connections \n\nThe `applications` table is the name of your overall application. The `services` table should contain the names of the individual microservices that make up your application. The `services_connections` should contain the connections between microservices. \n\nFor example, if your microservices were connected like in this image: \n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"90%\" src=\"./src/Images/Services-connections.png\" /\u003e\n\u003c/p\u003e\n\nthen the relevant columns of your services table would look something like this:\n\n| srv_id | srv_name       |\n|--------|----------------|\n| 1      | Authentication |\n| 2      | Image          |\n| 3      | Messaging      |\n\nand the services_connections table would look like this:\n\n| con_id | con_srv1 | con_srv2 |\n|--------|----------|----------|\n| 1      |  1       | 2        |\n| 2      |  1       | 3        |\n| 3      |  2       | 3        |\n\n\n---\n### Contributors\n| Team Member | LinkedIn | Github |\n|-------------|----------|--------|\n| **Matthew Allen**  |  [\u003cimg src=\"https://img.shields.io/badge/linkedin-%230077B5.svg?style=for-the-badge\u0026logo=linkedin\u0026logoColor=white\"\u003e](https://www.linkedin.com/in/matthew-allen-b0611868/) |  [\u003cimg src=\"https://img.shields.io/badge/GitHub-100000?style=for-the-badge\u0026logo=github\u0026logoColor=white\"\u003e](https://github.com/Allen726) |\n| **Emi Knox-Hershey**  | [\u003cimg src=\"https://img.shields.io/badge/linkedin-%230077B5.svg?style=for-the-badge\u0026logo=linkedin\u0026logoColor=white\"\u003e](https://www.linkedin.com/in/emiknoxhershey/)   | [\u003cimg src=\"https://img.shields.io/badge/GitHub-100000?style=for-the-badge\u0026logo=github\u0026logoColor=white\"\u003e](https://github.com/emi-kh)  |\n| **Myles Austin**  | [\u003cimg src=\"https://img.shields.io/badge/linkedin-%230077B5.svg?style=for-the-badge\u0026logo=linkedin\u0026logoColor=white\"\u003e](https://www.linkedin.com/in/mylesaustin/)   | [\u003cimg src=\"https://img.shields.io/badge/GitHub-100000?style=for-the-badge\u0026logo=github\u0026logoColor=white\"\u003e](https://github.com/mtv1243)  |\n| **Rick Markowitz**  | [\u003cimg src=\"https://img.shields.io/badge/linkedin-%230077B5.svg?style=for-the-badge\u0026logo=linkedin\u0026logoColor=white\"\u003e](https://www.linkedin.com/in/rickmarkowitz/)   |  [\u003cimg src=\"https://img.shields.io/badge/GitHub-100000?style=for-the-badge\u0026logo=github\u0026logoColor=white\"\u003e](https://github.com/rmarkowi1990) |\n\n---\nIf you found this interesting or helpful, feel free to drop a star on this project!\n\nYou can contribute by:\n- Raising issues you find in [GitHub Issues](https://github.com/oslabs-beta/LatenSee/issues)\n- Fixing issues by opening pull requests\n- Improving documentation\n\nIn order to run the test suite, you can use the following:\n\n```bash\nnpm install\nnpm run test\n```\n---\n### License\n\nTUBA-Tracing is distributed under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foslabs-beta%2Ftuba","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foslabs-beta%2Ftuba","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foslabs-beta%2Ftuba/lists"}