Write a README, and tweak the API a bit

README.md

@@ -1,35 +1,69 @@
-# DegicaDatadog
+# Degica Datadog
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/degica_datadog`. To experiment with that code, run `bin/console` for an interactive prompt.
+Internal library for StatsD and tracing.
 
-TODO: Delete this and the text above, and describe your gem
+## Setup
 
-## Installation
+1. Grab the gem from GitHub:
+    ```ruby
+    gem 'degica_datadog', git: 'https://github.com/degica/degica_datadog.git', branch: 'main'
+    ```
+1. Set the `SERVICE_NAME` environment variable to the name of your service.
+1. Then add this to your `config/application.rb` to enable tracing:
+    ```ruby
+    require "degica_datadog"
 
-Add this line to your application's Gemfile:
+    DegicaDatadog::Tracing::init
+    ```
+
+Note that you will need to manually setup log correlation for tracing if you use a custom logging setup. This is the relevant bit from `hats`:
 
 ```ruby
-gem 'degica_datadog'
+structured_log.merge!({
+  "dd.env" => Datadog::Tracing.correlation.env,
+  "dd.service" => Datadog::Tracing.correlation.service,
+  "dd.version" => Datadog::Tracing.correlation.version,
+  "dd.trace_id" => Datadog::Tracing.correlation.trace_id,
+  "dd.span_id" => Datadog::Tracing.correlation.span_id
+}.compact)
 ```
 
-And then execute:
-
-    $ bundle install
-
-Or install it yourself as:
-
-    $ gem install degica_datadog
-
-## Usage
+## StatsD
 
-TODO: Write usage instructions here
+This library exposes various different metric types. Please see the [Datadog Handbook](https://www.notion.so/The-Datadog-Handbook-b69e58b686f54bf795b36f97746a31ea) for details.
 
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+```ruby
+tags: {
+    some_tag: 42,
+}
+
+DegicaDatadog::Statsd::with_timing("my_timing", tags: tags) do
+    do_a_thing
+end
+DegicaDatadog::Statsd::count("my_count", amount: 1, tags: tags)
+DegicaDatadog::Statsd::gauge("my_gauge", 4, tags: tags)
+DegicaDatadog::Statsd::distribution("my_distribution", 8, tags: tags)
+DegicaDatadog::Statsd::set("my_distribution", payment, tags: tags)
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+## Tracing
 
-## Contributing
+The setup above auto-instruments many components of the system, but you can add additional spans or span tags:
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/sulami/degica_datadog.
+```ruby
+# Create a new span.
+DegicaDatadog::Tracing::span!("hats.process_payment") do
+  # Process a payment.
+end
+
+tags = {
+    "merchant_uuid" => merchant.uuid,
+    "merchant_name" => merchant.name,
+}
+
+# Add tags to the current span.
+DegicaDatadog::Tracing::span_tags!(**tags)
+
+# Add tags to the current root span.
+DegicaDatadog::Tracing::root_span_tags!(**tags)
+```

lib/degica_datadog/tracing.rb

@@ -32,11 +32,7 @@ def init # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
 
       # Start a new span.
       def span!(name, **options, &block)
-        if Config.enabled?
-          Datadog::Tracing.trace(name, **options, &block)
-        else
-          yield
-        end
+        Datadog::Tracing.trace(name, **options, &block)
       end
 
       # Set tags on the current tracing span.
@@ -51,7 +47,7 @@ def span_tags!(**tags)
 
       # Please don't use this. It's just a temporary thing until we can get the
       # statsd agent installed
-      def add_tags_to_root_span!(**tags)
+      def root_span_tags!(**tags)
         return unless Config.enabled?
 
         # forgive me my friends