{"id":16800540,"url":"https://github.com/derailed/ex_ray","last_synced_at":"2025-03-17T03:31:07.868Z","repository":{"id":57500915,"uuid":"108441257","full_name":"derailed/ex_ray","owner":"derailed","description":"An Elixir OpenTracing library based on Otter","archived":false,"fork":false,"pushed_at":"2019-01-22T11:03:33.000Z","size":225,"stargazers_count":58,"open_issues_count":4,"forks_count":12,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-12T04:24:06.647Z","etag":null,"topics":["elixir","opentracing","otter"],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/derailed.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-10-26T17:07:14.000Z","updated_at":"2025-02-06T02:39:54.000Z","dependencies_parsed_at":"2022-08-31T03:21:15.223Z","dependency_job_id":null,"html_url":"https://github.com/derailed/ex_ray","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/derailed%2Fex_ray","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/derailed%2Fex_ray/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/derailed%2Fex_ray/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/derailed%2Fex_ray/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/derailed","download_url":"https://codeload.github.com/derailed/ex_ray/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243841203,"owners_count":20356443,"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":["elixir","opentracing","otter"],"created_at":"2024-10-13T09:33:49.947Z","updated_at":"2025-03-17T03:31:07.539Z","avatar_url":"https://github.com/derailed.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ExRay\n\n\u003cdiv align=\"center\" style=\"margin-top:10px;\"\u003e\n  \u003cimg src=\"assets/xray.png\"/\u003e\n\u003c/div\u003e\n\n[![Hex version](https://img.shields.io/hexpm/v/ex_ray.svg \"Hex version\")](https://hex.pm/packages/ex_ray)\n[![Build Status](https://semaphoreci.com/api/v1/derailed/ex_ray/branches/master/shields_badge.svg)](https://semaphoreci.com/derailed/ex_ray)\n\n\n## Motivation\n\nExRay defines an annotation construct that wraps regular functions and enable\nthem to be traced using a simple affordance **@trace** to interact with an\nOpenTracing compliant collector.\n\n[OpenTracing](http://opentracing.io/) defines the concept of spans that\ntrack the call stack and record timing information and various call artifacts\nthat can be used for application runtime inspection.\nThis is a really cool piece of technology that compliments your monitoring\nsolution as you now have x-ray vision of your application at runtime once\na monitoring metric gets off the chart.\n\nHowever in practice, your code gets quickly cluttered by your tracing efforts.\nExRay alleviates the clutter by injecting cross-cutting tracing concern into\nyour application code. By using @trace annotation, you can trap the essence of\nthe calls without introducing tracing code mixed-in with your business logic.\n\nExRay leverages [Otter](https://github.com/Bluehouse-Technology/otter) Erlang\nOpenTracing lib from the fine folks of BlueHouse Technology.\n\n## Documentation\n\n[ExRay](https://hexdocs.pm/ex_ray)\n\n## Installation\n\nTracing information needs to be collected by a tracing backend of your choice. You can run\nExRay using any trace collector that Otter supports. In the following example we will use\n[Jaeger](https://uber.github.io/jaeger) from the self-driven folks at Uber!\n\n1. Start Jaeger\n\n    Providing you have docker running on you box, you can use the all-in-one Jaeger\n    image to get you started. If you are a Kubernetes fan, you can use the\n    [Jaeger chart](https://github.com/kubernetes/charts/tree/master/incubator/jaeger)\n\n    ```shell\n    docker run -d -e COLLECTOR_ZIPKIN_HTTP_PORT=9411 -p5775:5775/udp -p6831:6831/udp -p6832:6832/udp \\\n    -p5778:5778 -p16686:16686 -p14268:14268 -p9411:9411 jaegertracing/all-in-one:latest\n    ```\n\n    Alternatively, you could use the echo server [otter_srv](https://github.com/Bluehouse-Technology/otter_srv)\n    for testing your installation but I find it more fun to have a cool UI to look at your tracing outcomes.\n\n1. Setup Dependencies\n\n    Add the following dependencies to your project (Elixir or Phoenix)\n\n    \u003e NOTE: You can use Httpc(default), Hackney or IBrowse for your http client.\n    \u003e We opt for Ibrowse here.\n\n    ```elixir\n    def deps do\n      [\n        ...\n        {:ex_ray , \"~\u003e 0.1.2\"},\n        {:ibrowse, \"~\u003e 4.4.0\"}\n      ]\n    end\n    ```\n\n1. Configure Otter\n\n    In your config file, you need to tell Otter where to find your Zipkin collector.\n\n    ```elixir\n      config :otter,\n        zipkin_collector_uri:    'http://127.0.0.1:9411/api/v1/spans',\n        zipkin_tag_host_service: \"TraceMe\",\n        http_client:             :ibrowse\n      ```\n\n      \u003e Note: This thru me for a loop! The uri is indeed a char list and not a string!\n\n1. Configure Your Application\n\n    ExRay uses ETS to track the span chains. Each request will create a new chain that\n    will grow and collapse with your function call stack. As such you will need to track a unique\n    call ID either by generating a custom ID for each request. If you are using Phoenix, the\n    framework does this for you by using the request_id in the response headers.\n    The ETS table is used to locate the parent span for which to attach to when\n    navigating the call stack.\n\n    \u003e NOTE: One cool aspect of OpenTracing is the tracing does not stop at the process boundaries\n    as you can continue the chain to other processes and external services. Please see\n    the examples directory for further info.\n\n    In your application initialization, you need to make sure the ExRay ETS table is created by calling\n\n    ```elixir\n    # application.ex\n    ...\n    ExRay.Store.create()\n    ...\n    ```\n\n1. Let's Trace!\n\n    Here is a simples tracing example. Please take a look at the examples in the Repo and\n    [ExRay Tracers](https://github.com/derailed/ex_ray_tracers) for Phoenix sample use cases.\n\n    ```elixir\n      defmodule TraceMe do\n        use ExRay, pre: :before_fun, post: :after_fun\n\n        alias ExRay.Span\n\n        # Generates a request id\n        @req_id :os.system_time(:milli_seconds) |\u003e Integer.to_string |\u003e IO.inspect\n\n        @trace kind: :critical\n        def fred(a, b), do: a+b\n\n        defp before_fun(ctx) do\n          ctx.target\n          |\u003e Span.open(@req_id)\n          |\u003e :otter.tag(:kind, ctx.meta[:kind])\n          |\u003e :otter.log(\"\u003e\u003e\u003e #{ctx.target} with #{ctx.args |\u003e inspect}\")\n        end\n\n        defp after_fun(ctx, span, res) do\n          span\n          |\u003e :otter.log(\"\u003c\u003c\u003c #{ctx.target} returned #{res}\")\n          |\u003e Span.close(@req_id)\n        end\n      end\n    ```\n\n1. See it!\n\n    That's great, but how do you see the tracing information?\n\n    ```shell\n    open http://localhost:16686\n    ```\n\n    Under *Service* open up our *TraceMe* service, click **Find Traces** and you should\n    now see your span in all its glory ie timing, tag and log info\n\n---\n### Thank you for playing!\n\n---\n\u003cimg src=\"assets/imhoteplogo.png\" width=\"32\" height=\"auto\"/\u003e © 2017 Imhotep Software LLC.\nAll materials licensed under [Apache v2.0](http://www.apache.org/licenses/LICENSE-2.0)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fderailed%2Fex_ray","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fderailed%2Fex_ray","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fderailed%2Fex_ray/lists"}