{"id":25714031,"url":"https://github.com/patrick204nqh/trace_viz","last_synced_at":"2025-05-01T08:42:39.832Z","repository":{"id":267602325,"uuid":"899082580","full_name":"patrick204nqh/trace_viz","owner":"patrick204nqh","description":"Designed to trace and visualize events executed in a block of code. Useful for debugging and logging.","archived":false,"fork":false,"pushed_at":"2025-04-25T09:44:22.000Z","size":333,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-25T10:44:17.963Z","etag":null,"topics":["code-tracing","code-visualization","diagrams","method-tracing","ruby","trace-events","trace-point","tracing","visualization"],"latest_commit_sha":null,"homepage":"https://www.rubydoc.info/gems/trace_viz","language":"Ruby","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/patrick204nqh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","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}},"created_at":"2024-12-05T15:35:07.000Z","updated_at":"2025-04-25T09:44:24.000Z","dependencies_parsed_at":null,"dependency_job_id":"f90c12c6-f1de-4ead-b68c-538350bdb82f","html_url":"https://github.com/patrick204nqh/trace_viz","commit_stats":null,"previous_names":["patrick204nqh/trace_viz"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrick204nqh%2Ftrace_viz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrick204nqh%2Ftrace_viz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrick204nqh%2Ftrace_viz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrick204nqh%2Ftrace_viz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/patrick204nqh","download_url":"https://codeload.github.com/patrick204nqh/trace_viz/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251849436,"owners_count":21653885,"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":["code-tracing","code-visualization","diagrams","method-tracing","ruby","trace-events","trace-point","tracing","visualization"],"created_at":"2025-02-25T12:27:53.374Z","updated_at":"2025-05-01T08:42:39.820Z","avatar_url":"https://github.com/patrick204nqh.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# TraceViz\n\n[![Gem Version](https://badge.fury.io/rb/trace_viz.svg)](https://rubygems.org/gems/trace_viz)\n[![Downloads](https://img.shields.io/gem/dt/trace_viz)](https://rubygems.org/gems/trace_viz)\n[![Build Status](https://github.com/patrick204nqh/trace_viz/actions/workflows/ci.yml/badge.svg)](https://github.com/patrick204nqh/trace_viz/actions)\n[![Maintainability](https://api.codeclimate.com/v1/badges/e97579abe66f3477e71d/maintainability)](https://codeclimate.com/github/patrick204nqh/trace_viz/maintainability)\n[![Test Coverage](https://api.codeclimate.com/v1/badges/e97579abe66f3477e71d/test_coverage)](https://codeclimate.com/github/patrick204nqh/trace_viz/test_coverage)\n![License](https://img.shields.io/github/license/patrick204nqh/trace_viz)\n\nTraceViz is a Ruby library designed to trace and visualize events executed in a block of code. It is useful for logging, debugging, and generating diagrams to understand code execution and flow.\n\nThe gem allows you to customize how much detail you want to see, such as method calls, parameters, return values, and execution times.\n\n## Demo\n\n[![asciicast](https://asciinema.org/a/lKXPPgx0muZuQbtvMu8GyHaOV.svg)](https://asciinema.org/a/lKXPPgx0muZuQbtvMu8GyHaOV)\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```bash\ngem 'trace_viz'\n```\n\nAnd then execute:\n\n```bash\nbundle install\n```\n\nOr install it yourself as:\n\n```bash\ngem install trace_viz\n```\n\n## Usage\n\nWrap your code inside the TraceViz.trace block to start tracing its execution. The tracing behavior can be customized using various options:\n\n\u003cdetails\u003e\n  \u003csummary\u003eConfiguration Example\u003c/summary\u003e\n\n```ruby\nTraceViz.trace(\n  general: {\n    tab_size: 4,\n    show_indent: true,\n    show_depth: true,\n    max_display_depth: 3,\n    show_method_name: true,\n  },\n  source_location: {\n    show: false,\n    truncate_length: 100,\n  },\n  params: {\n    show: true,\n    mode: :name_and_value,\n    truncate_values: 50,\n  },\n  result: {\n    show: true,\n    truncate_length: 50,\n  },\n  execution: {\n    show_time: true,\n    show_trace_events: [:call, :return],\n  },\n  filters: [\n    :exclude_internal_call,\n    :exclude_default_classes,\n    ...\n  ],\n  export: {\n    enabled: true,\n    path: \"tmp\",\n    format: :txt,\n    overwrite: false,\n  }\n) do\n  # Your code here\nend\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eExample Code\u003c/summary\u003e\n\n```ruby\nclass Example\n  def perform_task(x, y)\n    result = add_numbers(x, y)\n    log_result(result)\n    result\n  end\n\n  def add_numbers(a, b)\n    sleep(0.1)\n    sum = a + b\n    multiply_by_factor(sum, 2)\n  end\n\n  def multiply_by_factor(value, factor)\n    sleep(0.05)\n    value * factor\n  end\n\n  def log_result(result)\n    sleep(0.02)\n    puts \"Final result: #{result}\"\n  end\nend\n\nTraceViz.trace(\n  general: {\n    tab_size: 4,\n    show_indent: true,\n    show_depth: true,\n    max_display_depth: 3,\n    show_method_name: true,\n  },\n  source_location: {\n    show: false,\n    truncate_length: 100,\n  },\n  params: {\n    show: true,\n    mode: :name_and_value,\n    truncate_values: 50,\n  },\n  result: {\n    show: true,\n    truncate_length: 50,\n  },\n  execution: {\n    show_time: true,\n    show_trace_events: [:call, :return],\n  },\n  filters: [\n    :exclude_internal_call,\n    include_classes: {\n      classes: [Example]\n    }\n  ],\n  export: {\n    enabled: true,\n    path: \"tmp\",\n    format: :txt, # Select :mermaid to export a mermaid diagram\n    overwrite: false,\n  }\n) do\n  example = Example.new\n  example.perform_task(5, 7)\nend\n```\n\n\u003c/details\u003e\n\n\u003cdetails open\u003e\n  \u003csummary\u003eSample Output\u003c/summary\u003e\n\n```bash\n🚀   [START]   #depth:0 Example#perform_task (5, 7)\n🚀   [START]       #depth:1 Example#add_numbers (5, 7)\n🚀   [START]           #depth:2 Example#multiply_by_factor (12, 2)\n🏁   [FINISH]          #depth:2 Example#multiply_by_factor #=\u003e 24\n🏁   [FINISH]      #depth:1 Example#add_numbers #=\u003e 24\n🚀   [START]       #depth:1 Example#log_result (24)\nFinal result: 24\n🏁   [FINISH]      #depth:1 Example#log_result #=\u003e nil\n🏁   [FINISH]  #depth:0 Example#perform_task #=\u003e 24\n```\n\n\u003c/details\u003e\n\n\u003cdetails open\u003e\n\u003csummary\u003eSample Diagram\u003c/summary\u003e\n\n```mermaid\nsequenceDiagram\n    box rgb(224, 236, 221) Example\n    participant E as Example\n    end\n    E -\u003e\u003e E: perform_task(x: 5, y: 7)\n    Note over E: 24\n    activate E\n    E -\u003e\u003e E: add_numbers(a: 5, b: 7)\n    Note over E: 24\n    activate E\n    E -\u003e\u003e E: multiply_by_factor(value: 12, factor: 2)\n    Note over E: 24\n    deactivate E\n    E -\u003e\u003e E: log_result(result: 24)\n    Note over E: nil\n    deactivate E\n```\n\n\u003c/details\u003e\n\n### Configuration Options\n\nTraceViz provides extensive configuration options to customize tracing behavior.\n\n| Group             | Option                     | Type             | Default Value               | Description                                                                      |\n| ----------------- | -------------------------- | ---------------- | --------------------------- | -------------------------------------------------------------------------------- |\n| `general`         | `tab_size`                 | Integer          | 2                           | Number of spaces for indentation.                                                |\n|                   | `mode`                     | Symbol           | `:summary`                  | Display mode (`:summary` or `:verbose`).                                         |\n|                   | `group_keys`               | Array of Symbols | `[:event, :klass, :action]` | Keys to group similar outputs.                                                   |\n|                   | `show_indent`              | Boolean          | true                        | Enables visual indentation for nested calls.                                     |\n|                   | `show_depth`               | Boolean          | true                        | Displays the depth level of the method call.                                     |\n|                   | `max_display_depth`        | Integer          | 3                           | Maximum depth of calls to display.                                               |\n|                   | `show_method_name`         | Boolean          | true                        | Logs the name of the method being executed.                                      |\n| `source_location` | `show`                     | Boolean          | false                       | Logs the source file and line number for methods.                                |\n|                   | `truncate_length`          | Integer          | 100                         | Maximum length of displayed source location information.                         |\n| `params`          | `show`                     | Boolean          | true                        | Logs method parameters.                                                          |\n|                   | `mode`                     | Symbol           | `:name_and_value`           | Parameter display mode (`:name`, `:value`, or `:name_and_value`).                |\n|                   | `truncate_values`          | Integer          | 50                          | Maximum length of parameter values to display.                                   |\n| `result`          | `show`                     | Boolean          | true                        | Logs method return values.                                                       |\n|                   | `truncate_length`          | Integer          | 50                          | Maximum length of return value logs.                                             |\n| `execution`       | `show_time`                | Boolean          | true                        | Logs execution time for methods.                                                 |\n|                   | `show_trace_events`        | Array of Symbols | `[:call, :return]`          | Specifies the trace events to log (e.g., `:call`, `:return`).                    |\n| `filters`         | `:exclude_internal_call`   | Symbol           | N/A                         | Exclude internal Ruby calls.                                                     |\n|                   | `:exclude_default_classes` | Symbol           | N/A                         | Skip logging standard library classes.                                           |\n|                   | `:exclude_rails_framework` | Symbol           | N/A                         | Ignore Rails framework classes and methods.                                      |\n|                   | `include_classes`          | Hash             | N/A                         | Specify classes to include in tracing.                                           |\n|                   | - `classes`                | Array            | []                          | List of class names to include (e.g., `[\"ClassName\"]`).                          |\n|                   | `exclude_classes`          | Hash             | N/A                         | Specify classes to exclude from tracing.                                         |\n|                   | - `classes`                | Array            | []                          | List of class names to exclude (e.g., `[\"ClassName\"]`).                          |\n|                   | `include_gems`             | Hash             | N/A                         | Include specific gems or runtime application gems.                               |\n|                   | - `app_running`            | Boolean          | true                        | Include the code of the application.                                             |\n|                   | - `app_path`               | String           | `Dir.pwd`                   | Path to the application (e.g., `Dir.pwd`).                                       |\n|                   | - `gems`                   | Array            | []                          | List of gems to include (e.g., `[\"gem1\", \"gem2\"]`).                              |\n|                   | `exclude_gems`             | Hash             | N/A                         | Exclude specified gems.                                                          |\n|                   | - `gems`                   | Array            | []                          | List of gems to exclude (e.g., `[\"excluded_gem\"]`).                              |\n| `export`          | `enabled`                  | Boolean          | true                        | Enables or disables exporting of trace logs.                                     |\n|                   | `path`                     | String           | `\"tmp\"`                     | Directory for exported trace logs.                                               |\n|                   | `format`                   | Symbol           | `:txt`                      | Format for trace logs. Use :txt for plain text or :mermaid for mermaid diagrams. |\n|                   | `overwrite`                | Boolean          | false                       | Prevents overwriting of existing exported files.                                 |\n\n### Notes\n\n- **Default Skipped Classes**: The following standard library classes are excluded by default when `:exclude_default_classes` is enabled:\n  - `Object`, `String`, `Array`, `Hash`, `Numeric`, `Integer`, `Float`, `Symbol`, `Kernel`, `Module`, `Class`, `Range`, `Regexp`, `Set`, `Gem`.\n\n## Documentation\n\nFor detailed API documentation, please visit [RubyDoc for trace_viz](https://www.rubydoc.info/gems/trace_viz).\n\n## Development\n\nTo set up your development environment:\n\n1. Clone the repository:\n\n```bash\ngit clone https://github.com/patrick204nqh/trace_viz.git\n```\n\n2. Navigate to the project directory:\n\n```bash\ncd trace_viz\n```\n\n3. Install dependencies:\n\n```bash\nbundle install\n```\n\n4. Run the test suite:\n\n```bash\nbin/rspec\n```\n\nYou can use `debug` or `pry` to test the gem locally. Make your changes, add tests, and ensure all tests pass before submitting a pull request.\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/patrick204nqh/trace_viz. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/patrick204nqh/trace_viz/blob/main/CODE_OF_CONDUCT.md).\n\n## License\n\nTraceViz is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatrick204nqh%2Ftrace_viz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpatrick204nqh%2Ftrace_viz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatrick204nqh%2Ftrace_viz/lists"}