naijacloud-argus 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 245ee709a587c9f68b9eef5f35f5e2a27105e0e2e8a2c58c0c3906a5021b3faf
+  data.tar.gz: 68f0528cdd050cc668eb0e2263ef5bd875e6aad21012fc1e1fcb3e2a5f8a50e8
+SHA512:
+  metadata.gz: 2ee64e8216a1b732fcaf87f1e2db53bfee3ee4ec012568a30eb53e9c70461eca5e312ca622bb25a38b0986712941bbf4e2e1c7db8e76a1df54dc24dafc52cee0
+  data.tar.gz: 50d4d3875834fa3523daed9638ab847be2eaa02defc8cbd33772d740945d671301bd150f971f21ffa07cf1c9bb379339de49a3e70b1561315a6c2491200c259c

data/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to `naijacloud-argus` are listed here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the gem uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-26
+
+First release, implementing the Argus SDK contract `argus.sdk/1`.
+
+### Added
+
+- `NaijaCloud::Argus.init`, with keywords or a block. Reads `ARGUS_DSN`,
+  `ARGUS_RELEASE` and `ARGUS_ENVIRONMENT`, then the `SENTRY_*` names. Without a
+  DSN every call is a no-op.
+- **Errors:** `capture_exception` (with the `cause` chain and source context
+  lines), `capture_message`, `set_user`, `set_tag(s)`, `set_context`,
+  `add_breadcrumb`, `with_scope`, `before_send`, `before_breadcrumb`,
+  `excluded_exceptions`. Sent as gzipped Sentry envelopes.
+- **Rails** (Railtie, no setup beyond `bundle add` and `ARGUS_DSN`): request
+  tracing named by route, unhandled exceptions, ActiveJob failures and spans, a
+  `Rails.error` subscriber, and optional `Rails.logger` forwarding
+  (`rails_logs`).
+- **Rack middleware** `NaijaCloud::Argus::Rack` for Sinatra, Hanami, Roda,
+  Grape and plain Rack: server spans continuing W3C `traceparent`, and
+  unhandled exceptions with the request.
+- **Outgoing `Net::HTTP`**: client spans, `traceparent` propagation and
+  breadcrumbs.
+- **Logs, metrics and traces** over OTLP/HTTP JSON: `log.info` and the other
+  levels, a `::Logger`-compatible `NaijaCloud::Argus::Logger`,
+  `metrics.count` / `gauge` / `distribution`, `trace` and `start_span`.
+- **Cron check-ins by monitor slug:** `cron.check_in` and `monitor`.
+- **Feature flags:** `flags.on?`, `flags.variant` and `flags.all`, cached 30 s.
+- **Transport:** one background thread and bounded queue per endpoint, retries
+  with backoff, `Retry-After` on 429, stops on a refused key, fork-safe, never
+  raises. Uncaught exceptions are reported and queues flushed at exit.
+- **Privacy defaults on:** sensitive keys, card numbers, tokens and JWTs are
+  filtered; query strings, cookies and IP addresses are not sent.
+
+[Unreleased]: https://github.com/naijacloud/argus-ruby/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/naijacloud/argus-ruby/releases/tag/v0.1.0

data/CONTRIBUTING.md

@@ -0,0 +1,93 @@
+# Contributing
+
+## Setup
+
+Nothing to install. The gem has no runtime dependencies, and minitest and rake
+ship with Ruby.
+
+```sh
+rake test
+```
+
+or, without bundler or rake at all:
+
+```sh
+ruby -Ilib -Itest test/errors_test.rb
+```
+
+## Tests
+
+The suite runs **offline**. `test/test_helper.rb` starts a small HTTP server on
+`127.0.0.1` with an ephemeral port, built on raw `TCPServer` (webrick left the
+standard library in Ruby 3.0). There is no WebMock and no VCR, and no test
+makes an outbound connection.
+
+```ruby
+@server.enqueue(status: 429, headers: { "Retry-After" => "7" })
+@server.enqueue(status: 500)
+```
+
+Unscripted requests get a 200. Gzipped bodies are decoded for you, and
+`envelope(request)` / `event_from(request)` parse an error envelope.
+
+Retry timing is asserted, not slept through: `capture_sleeps(client)` (or
+`transport.sleeper = ->(s) { ... }`) records the waits instead of waiting.
+
+**Rails.** `test/rails_test.rb` boots a minimal Rails app in a child process.
+It is skipped when Rails is not installed, which keeps the default suite
+dependency-free. To run it:
+
+```sh
+gem install railties activejob
+ruby -Ilib -Itest test/rails_test.rb
+```
+
+CI runs it against Rails 7.1, 7.2 and 8.0.
+
+**Contract test.** `rake contract` sends one of each signal to a real Argus
+and checks every endpoint answered 2xx:
+
+```sh
+ARGUS_CONTRACT_DSN=<dsn of a test source> rake contract
+```
+
+It expects a cron monitor with slug `argus-ruby-contract`; without one, the
+cron check-in's 404 is reported, not failed.
+
+## What to keep in mind when changing this gem
+
+- **The contract is binding.** `nc-argus/spec/README.md` (`argus.sdk/1`) is the
+  document every Argus SDK implements. A behaviour change here is owed to the
+  others too. If the contract and ingest disagree, ingest wins and the contract
+  gets fixed.
+- **Never raise into the app, never block it.** Public methods go through
+  `NaijaCloud::Argus.safely`; sending happens on the transport's threads.
+- **Zero runtime dependencies.** See SECURITY.md.
+- **Ruby 3.0 is the supported floor,** but keep the code 2.7-compatible: no
+  endless methods, no `Hash#except`, no pattern matching. And no keyword
+  arguments on a method that also takes an attributes hash: on Ruby 3 a
+  braceless `"key" => value` would be taken for keywords.
+
+## House style
+
+Comments explain **why**: the decision, the failure it prevents, the trap it
+avoids. `# frozen_string_literal: true` at the top of every file.
+
+## Releasing
+
+1. Update `lib/naijacloud/argus/version.rb`.
+2. Move the `Unreleased` changelog entries under `## [x.y.z] - YYYY-MM-DD` and
+   update the link definitions at the foot of the file.
+3. Tag and push: `git tag v<version> && git push origin v<version>`.
+
+`.github/workflows/release.yml` runs CI, refuses a tag that disagrees with
+`VERSION` or has no changelog section, builds and pushes the gem with RubyGems
+trusted publishing, then creates the GitHub release.
+
+### One-time setup
+
+- **rubygems.org → Settings → Trusted publishers → Create a pending trusted
+  publisher:** gem `naijacloud-argus`, owner `naijacloud`, repository
+  `argus-ruby`, workflow `release.yml`, environment `rubygems`.
+- **GitHub → Settings → Environments → New environment `rubygems`.** Add
+  required reviewers to make a push wait for a human.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NaijaCloud
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,255 @@
+<p align="center">
+  <a href="https://www.naijacloud.com/argus">
+    <img alt="Naijacloud Argus, Ruby SDK" src="https://raw.githubusercontent.com/naijacloud/argus-ruby/main/.github/assets/banner.png" width="100%">
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://rubygems.org/gems/naijacloud-argus"><img alt="gem" src="https://img.shields.io/badge/gem-naijacloud--argus-008751?style=flat-square&labelColor=0A0E0C"></a>
+  <img alt="ruby" src="https://img.shields.io/badge/ruby-%3E%3D_3.0-E0483F?style=flat-square&labelColor=0A0E0C">
+  <img alt="dependencies" src="https://img.shields.io/badge/dependencies-0-46C98A?style=flat-square&labelColor=0A0E0C">
+  <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-8A988F?style=flat-square&labelColor=0A0E0C"></a>
+</p>
+
+<p align="center">
+  <a href="#install">Install</a> ·
+  <a href="#rails">Rails</a> ·
+  <a href="#rack-sinatra-and-plain-ruby">Rack</a> ·
+  <a href="#errors">Errors</a> ·
+  <a href="#logs-metrics-and-traces">Logs, metrics, traces</a> ·
+  <a href="#cron-check-ins">Crons</a> ·
+  <a href="#feature-flags">Flags</a> ·
+  <a href="#privacy">Privacy</a> ·
+  <a href="#options">Options</a>
+</p>
+
+# naijacloud-argus
+
+The official Ruby SDK for [Argus](https://www.naijacloud.com/argus),
+Naijacloud's monitoring. One gem sends errors, logs, metrics, traces, cron
+check-ins and feature-flag checks, with one key: your app's **DSN**.
+
+It has no runtime dependencies (standard-library `net/http`, `json` and `zlib`
+only), implements the Argus SDK contract **`argus.sdk/1`**, and works for apps
+hosted anywhere, not only on Naijacloud.
+
+**Already using `sentry-ruby`?** Keep it. Argus accepts it: point its `dsn` at
+Argus and you're done. Switch to this gem when you want logs, metrics, cron
+check-ins and flags through the same setup.
+
+## Install
+
+```sh
+bundle add naijacloud-argus
+```
+
+Ruby 3.0 or newer. Copy the DSN (your app's key) from the source in Argus. It
+looks like `https://<key>@argus-in.naijacloud.com/<number>`.
+
+## Rails
+
+```sh
+bundle add naijacloud-argus
+ARGUS_DSN=https://…@argus-in.naijacloud.com/41 bin/rails server
+```
+
+That's the whole setup. The gem's Railtie:
+
+- **starts Argus** after your initializers, reading `ARGUS_DSN`,
+  `ARGUS_RELEASE` and `ARGUS_ENVIRONMENT` (falling back to `SENTRY_DSN`,
+  `SENTRY_RELEASE` and `SENTRY_ENVIRONMENT`). With no environment variable set,
+  the environment is `Rails.env` and the service name is your app's name;
+- **traces every request**, named by its route (`GET /orders/:id`), and
+  continues a `traceparent` header from the caller;
+- **reports unhandled exceptions** with the request they came from. A 404 or a
+  bad CSRF token is not reported;
+- **reports ActiveJob failures** with the job's class, id and queue, and traces
+  each job. Your `retry_on` and `discard_on` still behave as before;
+- **subscribes to `Rails.error`** (Rails 7.0+), so `Rails.error.report` and
+  `Rails.error.handle` reach Argus too;
+- **traces outgoing `Net::HTTP` calls** (and Faraday, HTTParty and anything else
+  built on it) and adds a `traceparent` header to them.
+
+Without a DSN it does nothing, so development and test need no changes. Apps
+hosted on Naijacloud get these variables set when the Argus tab is on.
+
+To change options, add an initializer. It runs before the Railtie's own start,
+so it wins:
+
+```ruby
+# config/initializers/argus.rb
+NaijaCloud::Argus.init do |c|
+  c.release = ENV["GIT_SHA"]
+  c.traces_sample_rate = 0.2
+  c.rails_logs = true   # also send Rails.logger lines to Argus Logs
+end
+```
+
+## Rack, Sinatra and plain Ruby
+
+```ruby
+# config.ru
+require "naijacloud/argus"
+NaijaCloud::Argus.init            # reads ARGUS_DSN
+use NaijaCloud::Argus::Rack
+run App
+```
+
+The middleware gives you the same request spans and error reports as on Rails,
+for Sinatra, Hanami, Roda, Grape and plain Rack.
+
+**In a script or a worker,** call `init` at the top. An exception that ends the
+process is reported, and whatever is queued is sent before the process exits.
+
+```ruby
+require "naijacloud/argus"
+NaijaCloud::Argus.init(dsn: ENV["ARGUS_DSN"], release: "1.4.2")
+```
+
+## Errors
+
+```ruby
+begin
+  charge_card(order)
+rescue Paystack::Error => e
+  NaijaCloud::Argus.capture_exception(e, tags: { provider: "paystack" }, extra: { order_id: order.id })
+  raise
+end
+
+NaijaCloud::Argus.capture_message("Webhook signature mismatch", level: :warning)
+NaijaCloud::Argus.set_user(id: current_user.id)
+NaijaCloud::Argus.set_tag("region", "af-west")
+NaijaCloud::Argus.add_breadcrumb(category: "cart", message: "coupon applied", data: { code: "NAIJA10" })
+```
+
+- **Causes:** an exception's `cause` chain is sent too.
+- **Duplicates:** the same exception object is sent once, however many layers
+  (Rack, `Rails.error`, ActiveJob) see it.
+- **Per request:** `set_user`, tags and breadcrumbs set during a request (or a
+  job) stay with that request; they don't leak to the next one on the same
+  thread or to other threads.
+- **`before_send`** lets you change an event (a Hash), or return `nil` to drop it.
+- `capture_exception` returns the event id, or `nil` when nothing was sent.
+
+## Logs, metrics and traces
+
+```ruby
+NaijaCloud::Argus.log.info("order placed", order_id: "ord_81", total: 18_500)
+NaijaCloud::Argus.log.error("paystack timed out", attempt: 3)
+
+NaijaCloud::Argus.metrics.count("orders.placed", 1, method: "card")
+NaijaCloud::Argus.metrics.gauge("queue.depth", jobs.size)
+NaijaCloud::Argus.metrics.distribution("checkout.ms", elapsed_ms, nil, "ms")
+
+NaijaCloud::Argus.trace("charge card", provider: "paystack") do |span|
+  span.set_attribute("amount", order.total)
+  paystack.charge(order)
+end
+```
+
+- **Logs** are sent in batches every 5 seconds (or every 1,000 lines). A line
+  written inside a request carries that request's trace id.
+- **A `::Logger`** that sends to Argus Logs, for any library that takes one:
+  `NaijaCloud::Argus::Logger.new(level: :info)`. On Rails 7.1+,
+  `Rails.logger.broadcast_to(NaijaCloud::Argus::Logger.new)` keeps your normal
+  log output and adds Argus (or set `rails_logs = true`).
+- **Metrics** are added up in the process and sent every 10 seconds.
+- **Spans** join the request or job they run in. `trace` returns the block's
+  value; an exception marks the span failed and is re-raised. For work that
+  doesn't fit a block, `span = NaijaCloud::Argus.start_span("upload")` and later
+  `span.finish` (or `span.finish(error)`).
+- **Propagate a trace** through something the gem doesn't instrument (a queue
+  message, gRPC metadata) with `NaijaCloud::Argus.traceparent`.
+- **Sample traces** with `traces_sample_rate` (0 to 1, default 1).
+
+## Cron check-ins
+
+Create a cron monitor in Argus first, then report runs by its slug:
+
+```ruby
+NaijaCloud::Argus.monitor("nightly-invoices") do
+  InvoiceRun.call
+end
+
+# or by hand:
+NaijaCloud::Argus.cron.check_in("nightly-invoices", :start)
+NaijaCloud::Argus.cron.check_in("nightly-invoices", :ok)    # or :error, or an exit code
+```
+
+`monitor` reports the start, then success or failure, and re-raises your job's
+exception. An unknown slug is answered 404 by Argus and dropped.
+
+## Feature flags
+
+```ruby
+if NaijaCloud::Argus.flags.on?("new-checkout", current_user.id)
+  # …
+end
+theme = NaijaCloud::Argus.flags.variant("theme", current_user.id, "light")
+NaijaCloud::Argus.flags.all(current_user.id)  # => {"new-checkout"=>"on", "theme"=>"dark"}
+```
+
+- **Caching:** answers are cached for 30 seconds per user (and attributes).
+- **Fallback:** if Argus can't be reached within 2 seconds, or the flag doesn't
+  exist, you get the fallback you passed.
+- **Targeting attributes** go last: `on?("beta", user.id, false, plan: "pro")`.
+
+## Privacy
+
+On by default:
+
+- The values of keys such as `password`, `token`, `secret`, `authorization`,
+  `cookie`, `bvn` and `card` are replaced with `[Filtered]`, at any depth: in
+  extra, contexts, breadcrumbs, log and span attributes.
+- Card numbers, bearer tokens, JWTs and `password=…` pairs are filtered inside
+  strings, including exception messages and log lines.
+- Query strings are removed from URLs in requests, breadcrumbs and spans.
+- Request bodies and cookies are never sent.
+- The user's IP address is not sent unless you set `send_default_pii: true`.
+
+Argus filters again on arrival.
+
+## Options
+
+Pass them to `init` as keywords, or set them in its block.
+
+| Option | Default | |
+| -- | -- | -- |
+| `dsn` | `ARGUS_DSN`, then `SENTRY_DSN` | Without one, nothing is sent |
+| `release` | `ARGUS_RELEASE`, then `SENTRY_RELEASE` | Your app's version, like `1.4.2` or a git commit |
+| `environment` | `ARGUS_ENVIRONMENT`, then `SENTRY_ENVIRONMENT`, else `production` (`Rails.env` on Rails) | |
+| `service_name` | `ARGUS_SERVICE_NAME`, else `app` (the app's name on Rails) | Shown on logs, metrics and traces |
+| `sample_rate` | `1.0` | Share of errors sent |
+| `traces_sample_rate` | `1.0` | Share of traces sent |
+| `send_default_pii` | `false` | Send the user's IP address |
+| `max_breadcrumbs` | `100` | |
+| `before_send` / `before_breadcrumb` | | Change or drop an event or crumb (return `nil`) |
+| `excluded_exceptions` | 404-type Rails errors | Class names never reported |
+| `project_root` | `Rails.root` on Rails | Frames under it are marked in-app |
+| `context_lines` | `true` | Send the lines of source around in-app frames |
+| `net_http` | `true` | Trace outgoing `Net::HTTP` calls |
+| `trace_propagation` | `true` | Add `traceparent` to outgoing requests |
+| `rails_logs` | `false` | Also send `Rails.logger` lines as logs |
+| `capture_at_exit` | `true` | Report the exception that ends the process |
+| `debug` | `false` | Print what the SDK does to `$stderr` (or `ARGUS_DEBUG=1`) |
+| `enabled` | `true` | Turn the SDK off without removing it |
+
+The gem never raises into your app and never blocks a request: everything is
+sent from background threads, with retries and backoff. Call
+`NaijaCloud::Argus.flush` before a short script exits if it calls `exit!`;
+otherwise the exit hook sends what's queued. It is safe with forking servers
+(Puma, Unicorn) and job runners (Sidekiq, Resque): each child process starts
+its own sender.
+
+## Not in this version
+
+These are planned, and not done yet:
+
+- automatic spans for ActiveRecord queries, Redis and view rendering;
+- trace propagation from a request into the jobs it enqueues;
+- reporting an ActiveJob failure only after its retries are used up (every
+  failed attempt is reported today).
+
+## License
+
+MIT

data/SECURITY.md

@@ -0,0 +1,60 @@
+# Security
+
+## Reporting a vulnerability
+
+Email **security@naijacloud.com**. Please do not open a public issue, and do not
+post a proof of concept anywhere public before we have shipped a fix.
+
+Include what you did, what happened, and the version of the gem. We acknowledge
+within two business days (West Africa Time) and will tell you what we intend to
+do and by when.
+
+## What the DSN is, and is not
+
+The DSN's key is a **public, send-only** credential: it can add events to one
+Argus source and read nothing. It is not a secret in the way an API key is, so
+a leaked DSN is a spam risk for that source, not a data breach. Rotate it from
+the source's settings if it is being abused.
+
+Even so, the gem keeps it tidy: on a server it travels in a header
+(`X-Sentry-Auth` or `Authorization: Bearer`), never in the URL, so it does not
+end up in proxy access logs. `Dsn#inspect` and `Client#inspect` do not print it.
+
+## What the gem does with your users' data
+
+The gem sits inside your app and sees its exceptions, requests and logs, so it
+is built to send as little as it can:
+
+1. **Sensitive keys are filtered before anything leaves the process,** at any
+   depth: `password`, `token`, `secret`, `authorization`, `cookie`, `bvn`,
+   `card`, `cvv`, `session` and the rest of the list in the Argus SDK contract
+   (§7). Card numbers (Luhn-checked), bearer/basic tokens, JWTs and
+   `password=…` pairs are filtered inside strings.
+2. **Request bodies and cookies are never sent.** Request headers are an
+   allowlist (host, user agent, accept, referer, request id, content type), not
+   a denylist, so a header nobody thought of is not sent.
+3. **Query strings are removed** from every URL the gem records.
+4. **IP addresses are not sent** unless you set `send_default_pii: true`.
+5. **TLS is verified** (`VERIFY_PEER`, set explicitly) and **redirects are never
+   followed**: a followed redirect would resend the key to a host the response
+   chose.
+6. **Debug output** (`debug: true`) prints what the SDK does, never payloads or
+   headers. `Net::HTTP#set_debug_output` is never called.
+
+Argus filters again on arrival; the gem does not rely on that.
+
+## Supply chain
+
+The gem has **zero runtime dependencies**. Everything is standard library:
+`net/http`, `openssl`, `json`, `zlib`, `securerandom`, `socket`, `uri`, and
+`logger` only if you use `NaijaCloud::Argus::Logger`.
+
+That is deliberate. This package runs in every process of the apps that use
+it, so every third-party dependency would be another maintainer whose account
+compromise becomes our customers' incident. Releases require MFA on the
+RubyGems account (`rubygems_mfa_required`).
+
+## Supported versions
+
+Security fixes are released for the latest minor version. Ruby 3.0 and newer
+are supported.