{"id":15023201,"url":"https://github.com/maraisr/rian","last_synced_at":"2025-10-06T01:19:44.616Z","repository":{"id":57355351,"uuid":"430704205","full_name":"maraisr/rian","owner":"maraisr","description":"👣 Effective tracing for the edge and origins","archived":false,"fork":false,"pushed_at":"2024-09-30T11:42:46.000Z","size":368,"stargazers_count":46,"open_issues_count":0,"forks_count":2,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-10T07:02:30.253Z","etag":null,"topics":["opentelemetry","opentracing","telemetry","tracer","tracing","zipkin"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/maraisr.png","metadata":{"funding":{"github":"maraisr"},"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}},"created_at":"2021-11-22T12:49:23.000Z","updated_at":"2025-02-25T04:23:39.000Z","dependencies_parsed_at":"2024-01-05T05:03:15.184Z","dependency_job_id":"fbe34976-bf6d-49da-a8ec-248a6dcc0b70","html_url":"https://github.com/maraisr/rian","commit_stats":{"total_commits":183,"total_committers":2,"mean_commits":91.5,"dds":0.005464480874316946,"last_synced_commit":"e10d70d0bea78638a66044d951d98ee5ef3371ee"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maraisr%2Frian","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maraisr%2Frian/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maraisr%2Frian/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maraisr%2Frian/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maraisr","download_url":"https://codeload.github.com/maraisr/rian/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245615005,"owners_count":20644376,"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":["opentelemetry","opentracing","telemetry","tracer","tracing","zipkin"],"created_at":"2024-09-24T19:58:49.839Z","updated_at":"2025-10-06T01:19:44.609Z","avatar_url":"https://github.com/maraisr.png","language":"TypeScript","funding_links":["https://github.com/sponsors/maraisr","https://www.buymeacoffee.com/marais"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"left\"\u003e\n\n\u003csamp\u003e\n\n\u003cimg src=\"files/logo-light.svg#gh-light-mode-only\" alt=\"rian light mode logo\" width=\"200px\"\u003e\n\u003cimg src=\"files/logo-dark.svg#gh-dark-mode-only\" alt=\"rian dark mode logo\" width=\"200px\"\u003e\n\n\u003c/samp\u003e\n\n**A utility to simplify your tracing**\n\n\u003ca href=\"https://npm-stat.com/charts.html?package=rian\"\u003e\n  \u003cimg src=\"https://badgen.net/npm/dm/rian?color=black\u0026label=npm%20downloads\" alt=\"js downloads\"\u003e\n\u003c/a\u003e\n\u003ca href=\"https://licenses.dev/npm/rian\"\u003e\n  \u003cimg src=\"https://licenses.dev/b/npm/rian?style=dark\" alt=\"licenses\" /\u003e\n\u003c/a\u003e\n\u003ca href=\"https://unpkg.com/rian/index.mjs\"\u003e\n  \u003cimg src=\"https://img.badgesize.io/https://unpkg.com/rian/index.mjs?compression=gzip\u0026label=gzip\u0026color=black\" alt=\"gzip size\" /\u003e\n\u003c/a\u003e\n\u003ca href=\"https://unpkg.com/rian/index.mjs\"\u003e\n  \u003cimg src=\"https://img.badgesize.io/https://unpkg.com/rian/index.mjs?compression=brotli\u0026label=brotli\u0026color=black\" alt=\"brotli size\" /\u003e\n\u003c/a\u003e\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n\u003csup\u003e\n\nThis is free to use software, but if you do like it, consider supporting me ❤️\n\n[![sponsor me](https://badgen.net/badge/icon/sponsor?icon=github\u0026label\u0026color=gray)](https://github.com/sponsors/maraisr)\n[![buy me a coffee](https://badgen.net/badge/icon/buymeacoffee?icon=buymeacoffee\u0026label\u0026color=gray)](https://www.buymeacoffee.com/marais)\n\n\u003c/sup\u003e\n\n\u003c/div\u003e\n\n## ⚡ Features\n\n- 🤔 **Familiar** — looks very much like opentelemetry.\n\n- ✅ **Simple** — `configure()` an environment, create a `tracer()`, `report()` and done.\n\n- 🏎 **Performant** — check the [benchmarks](#-benchmark).\n\n- 🪶 **Lightweight** — a mere 1KB and next to no [dependencies](https://npm.anvaka.com/#/view/2d/rian/).\n\n## 🚀 Usage\n\n\u003e Visit [/examples](/examples) for more!\n\n```ts\nimport { configure, tracer, report } from 'rian';\nimport { exporter } from 'rian/exporter.otel.http';\n\n// ~\u003e configure the environment, all tracers will inherit this\nconfigure('my-service', {\n  'service.version': 'DEV',\n});\n\n// ~\u003e create a tracer — typically \"per request\" or \"per operation\".\nconst trace = tracer('request');\n\nfunction handler(req) {\n  // ~\u003e start a span\n  return trace.span(`${req.method} ${req.path}`)(async (s) =\u003e {\n    // set some fields on this span's context\n    s.set_context({ user_id: req.params.user_id });\n\n    // ~\u003e span again for `db::read`\n    const data = await s.span('db::read')(() =\u003e db_execute('SELECT * FROM users'));\n\n    // ~\u003e maybe have some manual spanning\n    const processing_span = s.span('process records');\n\n    for (let row of data) {\n      processing_span.add_event('doing stuff', { id: row.id });\n      do_stuff(row);\n    }\n\n    // don't forget to end\n    processing_span.end();\n\n    return reply(200, { data });\n  });\n}\n\nconst otel_exporter = exporter((payload) =\u003e\n  fetch('/traces/otlp', {\n    method: 'POST',\n    body: JSON.stringify(payload),\n  }),\n);\n\nhttp.listen((req, executionCtx) =\u003e {\n  // ~\u003e report all the spans once the response is sent\n  executionCtx.defer(() =\u003e report(otel_exporter));\n  return handler(req);\n});\n```\n\nYou only need to `report` in your application once somewhere. All spans are collected into the same \"bucket\".\n\n\u003cdetails\u003e\u003csummary\u003eExample output\u003c/summary\u003e\n\nUsing: [examples/basic.ts](examples/basic.ts)\n\n```\n╭─ basic\n│        ╭─────────────────────────────────────────────────────────────────╮\n│  95 ms │ ┣━━━━━━━━━━┫                                                    │◗ setup\n│  41 ms │ ┣━━━━┫                                                          │◗ bootstrap\n│  32 ms │  ┣━━━┫                                                          │◗ building\n│  59 ms │           ┣━━━━━┫                                               │◗ precompile\n│  80 ms │             ┣━━━━━━━━┫                                          │◗ verify\n│  75 ms │                     ┣━━━━━━━┫                                   │◗ spawn thread\n│ 371 ms │                           ┣╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍╍┫ │◗ doesnt finish\n│ 347 ms │                           ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫   │◗ running\n│ 341 ms │                            ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫   │◗ e2e\n│  38 ms │                                                         ┣━━━┫   │◗ snapshot\n│  13 ms │                                                             ┣━┫ │◗ url for page /my-product/sle…\n│        ╰┼┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┼┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┼╯\n│         0 ms                      318.500 ms                       637 ms\n│\n│ one └┘ unit is less than: 10.443 ms\n│               total time:    637 ms\n╰─\n╭─ thread #1\n│       ╭──────────────────────────────────────────────────────────────────╮\n│ 20 ms │ ┣━━━━━━━━━━━━━━━━━━━━┫                                           │◗ setup\n│ 63 ms │ ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫ │◗ bootstrap\n│       ╰┼┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┼┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┴┼╯\n│        0 ms                       31.500 ms                        63 ms\n│\n│ one └┘ unit is less than: 1.016 ms\n│               total time:    63 ms\n╰─\n```\n\n\u003c/details\u003e\n\n## 🔎 API\n\n#### Module: [`rian`](./packages/rian/src/index.ts)\n\nThe main and _default_ module responsible for creating and provisioning spans.\n\n\u003e 💡 Note ~\u003e when providing span context values, you can use\n\u003e [Semantic Conventions](https://opentelemetry.io/docs/reference/specification/trace/semantic_conventions/), but won't\n\u003e be enforced.\n\n#### Module: [`rian/async`](./packages/rian/src/async.ts)\n\nA module that utilizes the `async_hooks` API to provide a `tracer` and `spans` that can be used where the current span\nisn't accessible.\n\n\u003e 💡 Note ~\u003e this module should be used mutually exclusively with the main `rian` module.\n\n\u003cdetails\u003e\n\n\u003csummary\u003eExample\u003c/summary\u003e\n\n```ts\nimport { configure, tracer, span, currentSpan, report } from 'rian/async';\nimport { exporter } from 'rian/exporter.otel.http';\n\nfunction handler(req) {\n  return span(`${req.method} ${req.path}`)(async () =\u003e {\n    const s = currentSpan();\n\n    s.set_context({ user_id: req.params.user_id });\n\n    const data = await s.span('db::read')(() =\u003e db_execute('SELECT * FROM users'));\n\n    const processing_span = s.span('process records');\n\n    for (let row of data) {\n      processing_span.add_event('doing stuff', { id: row.id });\n      do_stuff(row);\n    }\n\n    processing_span.end();\n\n    return reply(200, { data });\n  });\n}\n\nconst httpTrace = tracer('http');\n\nhttp.listen((req, executionCtx) =\u003e {\n  executionCtx.defer(() =\u003e report(exporter));\n  return httpTrace(() =\u003e handler(req));\n});\n```\n\n\u003c/details\u003e\n\n#### Module: [`rian/exporter.zipkin`](./packages/rian/src/exporter.zipkin.ts)\n\nExports the spans created using the zipkin protocol and leaves the shipping up to you.\n\n#### Module: [`rian/exporter.otel.http`](./packages/rian/src/exporter.otel.http.ts)\n\nImplements the OpenTelemetry protocol for use with http transports.\n\n## 🧑‍🍳 Exporter Recipes\n\n\u003cdetails\u003e\u003csummary\u003eNewRelic\u003c/summary\u003e\n\n```ts\nimport { configure, tracer, report } from 'rian';\nimport { exporter } from 'rian/exporter.zipkin';\n\nconst newrelic = exporter((payload) =\u003e\n  fetch('https://trace-api.newrelic.com/trace/v1', {\n    method: 'POST',\n    headers: {\n      'api-key': '\u003cyour api key\u003e',\n      'content-type': 'application/json',\n      'data-format': 'zipkin',\n      'data-format-version': '2',\n    },\n    body: JSON.stringify(payload),\n  }),\n);\n\nconfigure('my-service');\n\nconst tracer = tracer('app');\n\nawait report(newrelic);\n```\n\n[learn more](https://docs.newrelic.com/docs/distributed-tracing/trace-api/introduction-trace-api/)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eLightstep\u003c/summary\u003e\n\n```ts\nimport { configure, tracer, report } from 'rian';\nimport { exporter } from 'rian/exporter.otel.http';\n\nconst lightstep = exporter((payload) =\u003e\n  fetch('https://ingest.lightstep.com/traces/otlp/v0.9', {\n    method: 'POST',\n    headers: {\n      'lightstep-access-token': '\u003cyour api key\u003e',\n      'content-type': 'application/json',\n    },\n    body: JSON.stringify(payload),\n  }),\n);\n\nconfigure('my-service');\n\nconst tracer = tracer('app');\n\nawait report(lightstep);\n```\n\n[learn more](https://opentelemetry.lightstep.com/tracing/)\n\n\u003c/details\u003e\n\n## 🤔 Motivation\n\nTo clarify, `rian` is the Irish word for \"trace\".\n\nIn our efforts to be observant citizens, we often rely on tools such as NewRelic, Lightstep, and Datadog. However, these\ntools can be bloated and slow, often performing too many unnecessary tasks and driving up costs, as every span costs.\n\nThis is where rian comes in as a lightweight, fast, and effective tracer inspired by industry giants OpenTracing and\nOpenTelemetry. These frameworks were designed to abstract the telemetry part from vendors, allowing libraries to be\ninstrumented without needing to know about the vendor.\n\nRian does not intend to align or compete with them, slightly different goals. Rian aims to be used exclusively for\ninstrumenting your application, particularly critical business paths. While rian can scale to support more complex\nconstructs, there are profiler tools that are better suited for those jobs. Rian's primary design goal is to provide\nbetter insights into your application's behavior, particularly for edge or service workers where a lean tracer is\nfavored.\n\nRian does not by design handle injecting [`w3c trace-context`](https://www.w3.org/TR/trace-context/), or\n[propagating baggage](https://www.w3.org/TR/baggage/). But we do expose api's for achieving this.\n\n## 💨 Benchmark\n\n\u003e via the [`/bench`](/bench) directory with Node v17.2.0\n\n```\nValidation :: single span\n✔ rian\n✔ rian/async\n✔ opentelemetry\n\nBenchmark :: single span\n  rian                   x 277,283 ops/sec ±3.57% (90 runs sampled)\n  rian/async             x 279,525 ops/sec ±2.33% (91 runs sampled)\n  opentelemetry          x 155,019 ops/sec ±13.13% (70 runs sampled)\n\nValidation :: child span\n✔ rian\n✔ rian/async\n✔ opentelemetry\n\nBenchmark :: child span\n  rian                   x 146,793 ops/sec ±3.38% (87 runs sampled)\n  rian/async             x 180,488 ops/sec ±1.64% (92 runs sampled)\n  opentelemetry          x 102,541 ops/sec ±9.77% (73 runs sampled)\n```\n\n\u003e And please... I know these results are anything but the full story. But it's a number and point on comparison.\n\n## License\n\nMIT © [Marais Rossouw](https://marais.io)\n\n##### Disclaimer\n\n\u003csup\u003e- NewRelic is a registered trademark of https://newrelic.com/ and not affiliated with this project.\u003c/sup\u003e\u003cbr\u003e\n\u003csup\u003e- Datadog is a registered trademark of https://www.datadoghq.com/ and not affiliated with this project.\u003c/sup\u003e\u003cbr\u003e\n\u003csup\u003e- Lightstep is a registered trademark of https://lightstep.com/ and not affiliated with this project.\u003c/sup\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaraisr%2Frian","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaraisr%2Frian","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaraisr%2Frian/lists"}