{"id":13651280,"url":"https://github.com/opencensus-beam/opencensus_absinthe","last_synced_at":"2025-12-11T23:36:49.361Z","repository":{"id":55986602,"uuid":"184836859","full_name":"opencensus-beam/opencensus_absinthe","owner":"opencensus-beam","description":"Opencensus integration with Absinthe","archived":false,"fork":false,"pushed_at":"2020-07-30T13:38:05.000Z","size":39,"stargazers_count":21,"open_issues_count":12,"forks_count":5,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-03-14T16:24:06.816Z","etag":null,"topics":["absinthe","elixir","opencensus","tracing"],"latest_commit_sha":null,"homepage":null,"language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/opencensus-beam.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}},"created_at":"2019-05-04T00:50:51.000Z","updated_at":"2022-11-03T20:25:16.000Z","dependencies_parsed_at":"2022-08-15T10:50:40.769Z","dependency_job_id":null,"html_url":"https://github.com/opencensus-beam/opencensus_absinthe","commit_stats":null,"previous_names":["amplifiedai/opencensus_absinthe"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opencensus-beam%2Fopencensus_absinthe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opencensus-beam%2Fopencensus_absinthe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opencensus-beam%2Fopencensus_absinthe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opencensus-beam%2Fopencensus_absinthe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/opencensus-beam","download_url":"https://codeload.github.com/opencensus-beam/opencensus_absinthe/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248092123,"owners_count":21046415,"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":["absinthe","elixir","opencensus","tracing"],"created_at":"2024-08-02T02:00:47.493Z","updated_at":"2025-12-11T23:36:49.324Z","avatar_url":"https://github.com/opencensus-beam.png","language":"Elixir","funding_links":[],"categories":["Tracing"],"sub_categories":[],"readme":"# Opencensus.Absinthe\n\n[![CircleCI](https://circleci.com/gh/opencensus-beam/opencensus_absinthe.svg?style=svg)](https://circleci.com/gh/opencensus-beam/opencensus_absinthe)\n[![Hex version badge](https://img.shields.io/hexpm/v/opencensus_absinthe.svg)](https://hex.pm/packages/opencensus_absinthe)\n\nExtends [Absinthe] to automatically create [OpenCensus] spans. Designed to\nwork with whatever is producing spans upstream, e.g. [Opencensus.Plug].\n\n[Absinthe]: http://absinthe-graphql.org\n[Opencensus.Plug]: https://github.com/opencensus-beam/opencensus_plug\n[OpenCensus]: http://opencensus.io\n\n## Installation\n\n* Take the dependency\n* Set up the pipeline\n* Set up the middleware\n* Adjust your schema\n* Check it's all working\n\n### Dependency\n\nIf you're using `Absinthe.Plug`, add `opencensus_absinthe` to your `deps`\nin `mix.exs` using a tighter version constraint than:\n\n```elixir\n{:absinthe_plug, \"\u003e= 0.0.0\"},\n{:opencensus_absinthe, \"\u003e= 0.0.0\"},\n```\n\n### Pipeline\n\nAdd a `:pipeline` to your `t:Absinthe.Plug.opts/0` to have it call\n`Opencensus.Absinthe.Plug.traced_pipeline/2`. If you're using\n`Phoenix.Router.forward/4`, for example:\n\n```elixir\nforward(\n  path,\n  Absinthe.Plug,\n  # ... existing config ...\n  pipeline: {Opencensus.Absinthe.Plug, :traced_pipeline}\n)\n```\n\nIf you already have a `pipeline`, you can define your own and call both to\ninsert their phases. To work with `ApolloTracing`, for example:\n\n```elixir\ndef your_custom_pipeline(config, pipeline_opts \\\\ []) do\n  config\n  |\u003e Absinthe.Plug.default_pipeline(pipeline_opts)\n  |\u003e ApolloTracing.Pipeline.add_phases()\n  |\u003e Opencensus.Absinthe.add_phases()\nend\n```\n\nWorst case, you'll need to copy the code from the current `pipeline` target\nand add a call to `Opencensus.Absinthe.add_phases/1` as above.\n\n### Middleware\n\nYour [middleware callback][c:middleware/3] needs to run its output through\nthe matching function in `Opencensus.Absinthe.Middleware` to add the\nmiddleware to only the fields that need it:\n\n```elixir\ndef middleware(middleware, field, object) do\n  Opencensus.Absinthe.middleware(middleware, field, object)\nend\n```\n\nIf you've already got some middleware, like above, you might need to copy\nsome code around to get the job done:\n\n```elixir\ndef middleware(middleware, field, object) do\n  ([ApolloTracing.Middleware.Tracing, ApolloTracing.Middleware.Caching] ++ middleware)\n  |\u003e Opencensus.Absinthe.middleware(field, object)\nend\n```\n\n[c:middleware/3]: https://hexdocs.pm/absinthe/Absinthe.Schema.html#c:middleware/3\n\n### Schema\n\nUntil Absinthe merge and publish their telemetry support (see below) _and_\nyou upgrade, you'll also need to set `:trace` in the metadata for any\n`field` for which you want tracing to happen:\n\n```elixir\n  query do\n    @desc \"List all the things\"\n    field :things, list_of(:thing), meta: [trace: true] do\n      resolve(\u0026Resolvers.Account.all_things/2)\n    end\n```\n\nOnce you're on a telemetry-capable Absinthe, you'll get tracing for every\n`field` containing a `resolve`.\n\n### Verification\n\nCheck your installation with `iex -S mix phx.server`, assuming Phoenix, and:\n\n    iex\u003e :oc_reporter.register(:oc_reporter_stdout)\n    :ok\n\nFire off a few requests and check the `{span, \u003c\u003cNAME\u003e` lines on standard\noutput.\n\n* If you see names matching your GraphQL route, e.g. `\u003c\u003c/api\u003e\u003e`, you set up\n  `opencensus_plug` properly.\n\n* If you see `\u003c\u003c\"Absinthe.Blueprint\"\u003e\u003e`, the pipeline is working.\n\n* If you see `\u003c\u003c\"YourProject.Schema:thefield\"\u003e\u003e`, the middleware is working\n  and you've either:\n\n  * Added `meta: [trace: true]` to your `field :thefield` as above, or\n\n  * Upgraded to a telemetry-capable Absinthe.\n\n## Behaviour\n\nEach Absinthe query runs in the process of its caller. If you hook up\n[`opencensus_plug`][opencensus_plug], or something else that'll take trace\ndetails off the wire, the process dictionary will have an `:oc_span_ctx_key`\nkey used by [`opencensus`][opencensus] to keep track of spans in flight.\n\nThis package adds new [phases] to your [Absinthe Pipeline][pipeline]\nto start new spans for each [resolution] and call, using both methods\navailable:\n\n\u003e `opencensus` provides two methods for tracking \\[trace and span] context,\n\u003e the process dictionary and a variable holding a ctx record.\n\nSpecifically, this package:\n\n* Starts a new span registered in the process dictionary for each query, and\n\n* _Without any use of the process dictionary_, starts a new span for each\n  field, using the query span as the parent.\n\nThe latter is necessary because the fields don't necessarily start and stop\nwithout overlap. Naïve use of `:ocp.with_child_span` and `:ocp.finish_span`\nwill yield incorrect traces.\n\n[pipeline]: https://hexdocs.pm/absinthe/Absinthe.Pipeline.html\n[phases]: https://hexdocs.pm/absinthe/Absinthe.Phase.html\n[resolution]: https://hexdocs.pm/absinthe/Absinthe.Resolution.html\n[opencensus]: https://hex.pm/packages/opencensus\n[opencensus_plug]: https://hex.pm/packages/opencensus_plug\n\n## Development\n\nDependency management:\n\n* `mix deps.get` to get your dependencies\n* `mix deps.compile` to compile them\n* `mix licenses` to check their license declarations, recursively\n\nFinding problems:\n\n* `mix compile` to compile your code\n* `mix credo` to suggest more idiomatic style for it\n* `mix dialyzer` to find problems static typing might spot... *slowly*\n* `mix test` to run unit tests\n* `mix test.watch` to run the tests again whenever you change something\n* `mix coveralls` to check test coverage\n\nDocumentation:\n\n* `mix docs` to generate documentation for this project\n* `mix help` to find out what else you can do with `mix`\n\n### Next Steps\n\nObvious next steps include stronger tests and many minor tweaks:\n\n* Rename the outer span according to the schema\n* Set some attributes on the outer span\n* Trim the path from references so it starts with the closest `lib`\n* Set the span status on completion\n* Retire `lib/opencensus/absinthe/logger.ex` when possible\n\nThe biggest looming change would be telemetry integration:\n\n[`absinthe-graphql/absinthe#663`][PR663] to add [`telemetry`][telemetry] to\nAbsinthe could give us start and stop calls from within the calling process\nsuitable for calling `:ocp.with_child_span` and `:ocp.finish_span` to\nmaintain the main trace. In turn, that'd mean we didn't need the pipeline.\n\n`#663` won't help us generate spans for fields, because there's no way to\npass state back through `:telemetry.execute`. That said, it'll automatically\nset `:absinthe_telemetry` in the field metadata if `query` is present.\n\n[PR663]: https://github.com/absinthe-graphql/absinthe/pull/663\n[telemetry]: https://hex.pm/packages/telemetry\n\nRather than push back on the telemetry support to make it better support\ntracing, we could integrate this capability directly with Absinthe if:\n\n* The community deploy a lot of `opencensus`\n* It proves to be as lightweight and stable as `telemetry`\n* Its impact when not hooked up is minimal or zero\n\nWe could then retire this module except for users with older versions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopencensus-beam%2Fopencensus_absinthe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopencensus-beam%2Fopencensus_absinthe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopencensus-beam%2Fopencensus_absinthe/lists"}