From 1dccc8e19b447e64951be75f0c6aa7335006a89f Mon Sep 17 00:00:00 2001 From: Andrey Date: Tue, 23 Apr 2024 14:02:04 +0200 Subject: [PATCH 1/6] update readme to reflect most recent recommendations and add upgrade guide for users upgrading from ddtrace --- README.md | 79 +++++++++++++++++++------------------------- docs/UpgradeGuide.md | 50 ++++++++++++++++++++++++++++ 2 files changed, 84 insertions(+), 45 deletions(-) create mode 100644 docs/UpgradeGuide.md diff --git a/README.md b/README.md index 13196129..25b1b6ef 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,10 @@ group :test do end ``` +## Upgrade from ddtrace v1.x + +If you used test visibility for Ruby with ddtrace gem, check out our [upgrade guide](/docs/UpgradeGuide.md). + ## Usage ### RSpec @@ -31,25 +35,14 @@ require 'datadog/ci' # Only activates test instrumentation on CI if ENV["DD_ENV"] == "ci" Datadog.configure do |c| - # Configures the tracer to ensure results delivery - c.ci.enabled = true - # The name of the service or library under test c.service = 'my-ruby-app' - - # Enables the RSpec instrumentation - c.ci.instrument :rspec, **options + c.ci.enabled = true + c.ci.instrument :rspec end end ``` -`options` are the following keyword arguments: - -| Key | Description | Default | -| --- | ----------- | ------- | -| `enabled` | Defines whether RSpec tests should be traced. Useful for temporarily disabling tracing. `true` or `false` | `true` | -| `service_name` | Service name used for `rspec` instrumentation. | `'rspec'` | - ### Minitest The Minitest integration will trace all executions of tests when using `minitest` test framework. @@ -64,13 +57,10 @@ require 'datadog/ci' if ENV["DD_ENV"] == "ci" # Configure default Minitest integration Datadog.configure do |c| - # Configures the tracer to ensure results delivery - c.ci.enabled = true - # The name of the service or library under test c.service = 'my-ruby-app' - - c.ci.instrument :minitest, **options + c.ci.enabled = true + c.ci.instrument :minitest end end ``` @@ -87,20 +77,13 @@ require 'minitest/autorun' if ENV["DD_ENV"] == "ci" Datadog.configure do |c| - c.ci.enabled = true c.service = 'my-ruby-app' + c.ci.enabled = true c.ci.instrument :minitest end end ``` -`options` are the following keyword arguments: - -| Key | Description | Default | -| --- | ----------- | ------- | -| `enabled` | Defines whether Minitest tests should be traced. Useful for temporarily disabling tracing. `true` or `false` | `true` | -| `service_name` | Service name used for `minitest` instrumentation. | `'minitest'` | - ### Cucumber Activate `Cucumber` integration with configuration @@ -112,24 +95,31 @@ require 'datadog/ci' # Only activates test instrumentation on CI if ENV["DD_ENV"] == "ci" Datadog.configure do |c| - # Configures the tracer to ensure results delivery - c.ci.enabled = true - # The name of the service or library under test c.service = 'my-ruby-app' - - # Enables the Cucumber instrumentation - c.ci.instrument :cucumber, **options + c.ci.enabled = true + c.ci.instrument :cucumber end end ``` -`options` are the following keyword arguments: +### Instrumentation options + +Configuration `ci.instrument` accepts the following optional parameters: + +- `enabled` (default: `true`) - defines whether tests should be traced (useful for temporarily disabling tracing) +- `service_name` - service name used for this instrumentation (when you want it to be different for given test framework) -| Key | Description | Default | -| --- | ----------- | ------- | -| `enabled` | Defines whether Cucumber tests should be traced. Useful for temporarily disabling tracing. `true` or `false` | `true` | -| `service_name` | Service name used for `cucumber` instrumentation. | `'cucumber'` | +Example usage: + +```ruby + Datadog.configure do |c| + c.service = 'my-ruby-app' + c.ci.enabled = true + c.ci.instrument :cucumber, service_name: 'my-cucumber-features', enabled: true + c.ci.instrument :minitest, service_name: 'my-unit-tests', enabled: false + end +``` ## Agentless mode @@ -154,7 +144,7 @@ or other external calls like here: ![Test trace with redis instrumented](./docs/screenshots/test-trace-with-redis.png) -In order to achieve this you can configure ddtrace instrumentations in your configure block: +In order to achieve this you can configure Datadog tracing instrumentations in your configure block: ```ruby Datadog.configure do |c| @@ -167,13 +157,13 @@ end ...or enable auto instrumentation in your test_helper/spec_helper: ```ruby -require "ddtrace/auto_instrument" +require "datadog/auto_instrument" ``` Note: in CI mode these traces are going to be submitted to CI Visibility, they will **not** show up in Datadog APM. -For the full list of available instrumentations see [ddtrace documentation](https://github.com/DataDog/dd-trace-rb/blob/master/docs/GettingStarted.md) +For the full list of available instrumentations see [datadog documentation](https://github.com/DataDog/dd-trace-rb/blob/master/docs/GettingStarted.md) ### WebMock @@ -187,8 +177,7 @@ Webmock accordingly. ```ruby # when using agentless mode -# note to use the correct datadog site (e.g. datadoghq.eu, etc) -WebMock.disable_net_connect!(:allow => /datadoghq.com/) +WebMock.disable_net_connect!(:allow => /datadoghq/) # when using agent WebMock.disable_net_connect!(:allow_localhost => true) @@ -212,7 +201,7 @@ VCR.configure do |config| # when using agentless mode # note to use the correct datadog site (e.g. datadoghq.eu, etc) - config.ignore_hosts "citestcycle-intake.datadoghq.com", "api.datadoghq.com" + config.ignore_hosts "citestcycle-intake.datadoghq.com", "api.datadoghq.com", "citestcov-intake.datadoghq.com" end ``` @@ -220,7 +209,7 @@ end Startup logs produce a report of tracing state when the application is initially configured. These logs are activated by default in test mode, if you don't want them you can disable this -via `diagnostics.startup_logs.enabled = false` or `DD_TRACE_STARTUP_LOGS=0`. +via `DD_TRACE_STARTUP_LOGS=0` or in the configure block: ```ruby Datadog.configure { |c| c.diagnostics.startup_logs.enabled = false } @@ -230,7 +219,7 @@ Datadog.configure { |c| c.diagnostics.startup_logs.enabled = false } Switching the library into debug mode will produce verbose, detailed logs about tracing activity, including any suppressed errors. This output can be helpful in identifying errors, confirming trace output, or catching HTTP transport issues. -You can enable this via `diagnostics.debug = true` or `DD_TRACE_DEBUG=1`. +You can enable this via `DD_TRACE_DEBUG=1` or in the configure block: ```ruby Datadog.configure { |c| c.diagnostics.debug = true } diff --git a/docs/UpgradeGuide.md b/docs/UpgradeGuide.md new file mode 100644 index 00000000..53f81387 --- /dev/null +++ b/docs/UpgradeGuide.md @@ -0,0 +1,50 @@ +# Upgrading from ddtrace 1.x to datadog-ci + +Test visibility for Ruby is no longer part of `datadog` gem and fully migrated to +`datadog-ci` gem. To continue using it after gem `datadog` v2.0 is released, only a +couple of changes needed. + +## Add datadog-ci to your gemfile + +Before: + +```ruby +gem "ddtrace", "~> 1.0" +``` + +After: + +```ruby +group :test do + gem "datadog-ci", "~> 1.0" +end +``` + +Or if you use other Datadog products: + +```ruby +gem "datadog", "~> 2.0" + +group :test do + gem "datadog-ci", "~> 1.0" +end +``` + +## Change WebMock or VCR configuration + +We work on adding new features to the test visibility product in Ruby (intelligent test runner, git metadata upload, code coverage support) that require new endpoints being allowlisted by WebMock/VCR tools when using agentless mode. + +For WebMock allow all requests that match datadoghq: + +```ruby +WebMock.disable_net_connect!(:allow => /datadoghq/) +``` + +For VCR provide a list of Datadog backend hosts as ignored hosts: + +```ruby +VCR.configure do |config| + # note to use the correct datadog site (e.g. datadoghq.eu, etc) + config.ignore_hosts "citestcycle-intake.datadoghq.com", "api.datadoghq.com", "citestcov-intake.datadoghq.com" +end +``` From 12b52b7c7825d5d4fd826cf359b4aac07b86389f Mon Sep 17 00:00:00 2001 From: Andrey Marchenko <426400+anmarchenko@users.noreply.github.com> Date: Tue, 23 Apr 2024 16:03:51 +0200 Subject: [PATCH 2/6] Simplify wording MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Juan Antonio Fernández de Alba --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 25b1b6ef..5693a70a 100644 --- a/README.md +++ b/README.md @@ -144,7 +144,7 @@ or other external calls like here: ![Test trace with redis instrumented](./docs/screenshots/test-trace-with-redis.png) -In order to achieve this you can configure Datadog tracing instrumentations in your configure block: +To achieve this, add Datadog tracing instrumentations in your `Datadog.configure` block: ```ruby Datadog.configure do |c| From 9272bc22cf20bbde440569ebf8eea7d46a95c149 Mon Sep 17 00:00:00 2001 From: Andrey Marchenko <426400+anmarchenko@users.noreply.github.com> Date: Tue, 23 Apr 2024 16:06:55 +0200 Subject: [PATCH 3/6] Update docs/UpgradeGuide.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Juan Antonio Fernández de Alba --- docs/UpgradeGuide.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/UpgradeGuide.md b/docs/UpgradeGuide.md index 53f81387..3f0035a0 100644 --- a/docs/UpgradeGuide.md +++ b/docs/UpgradeGuide.md @@ -1,8 +1,7 @@ # Upgrading from ddtrace 1.x to datadog-ci Test visibility for Ruby is no longer part of `datadog` gem and fully migrated to -`datadog-ci` gem. To continue using it after gem `datadog` v2.0 is released, only a -couple of changes needed. +`datadog-ci` gem. To continue using it after gem `datadog` v2.0 is released, do these changes. ## Add datadog-ci to your gemfile From 3fbaf5bb9c2cb2f2758d2ca66f562014e5b12e94 Mon Sep 17 00:00:00 2001 From: Andrey Marchenko <426400+anmarchenko@users.noreply.github.com> Date: Tue, 23 Apr 2024 16:08:53 +0200 Subject: [PATCH 4/6] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Juan Antonio Fernández de Alba --- README.md | 2 +- docs/UpgradeGuide.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5693a70a..c099ce5c 100644 --- a/README.md +++ b/README.md @@ -209,7 +209,7 @@ end Startup logs produce a report of tracing state when the application is initially configured. These logs are activated by default in test mode, if you don't want them you can disable this -via `DD_TRACE_STARTUP_LOGS=0` or in the configure block: +via `DD_TRACE_STARTUP_LOGS=0` or in the `Datadog.configure` block: ```ruby Datadog.configure { |c| c.diagnostics.startup_logs.enabled = false } diff --git a/docs/UpgradeGuide.md b/docs/UpgradeGuide.md index 3f0035a0..f0e5bd32 100644 --- a/docs/UpgradeGuide.md +++ b/docs/UpgradeGuide.md @@ -31,7 +31,7 @@ end ## Change WebMock or VCR configuration -We work on adding new features to the test visibility product in Ruby (intelligent test runner, git metadata upload, code coverage support) that require new endpoints being allowlisted by WebMock/VCR tools when using agentless mode. +Test visibility features (such as intelligent test runner, git metadata upload, code coverage support) require some DataDog endpoints to be allowlisted by WebMock/VCR tools when using agentless mode. For WebMock allow all requests that match datadoghq: From 576d656bc963be64a6e7f08df26a2f7c0a110fb9 Mon Sep 17 00:00:00 2001 From: Andrey Date: Tue, 23 Apr 2024 16:14:26 +0200 Subject: [PATCH 5/6] upgrade guide: a bunch of changes from code review --- README.md | 6 +++--- docs/UpgradeGuide.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index c099ce5c..ab6c6dc1 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ end ## Upgrade from ddtrace v1.x -If you used test visibility for Ruby with ddtrace gem, check out our [upgrade guide](/docs/UpgradeGuide.md). +If you used [test visibility for Ruby](https://docs.datadoghq.com/tests/setup/ruby/) with [ddtrace](https://github.com/datadog/dd-trace-rb) gem, check out our [upgrade guide](/docs/UpgradeGuide.md). ## Usage @@ -108,7 +108,7 @@ end Configuration `ci.instrument` accepts the following optional parameters: - `enabled` (default: `true`) - defines whether tests should be traced (useful for temporarily disabling tracing) -- `service_name` - service name used for this instrumentation (when you want it to be different for given test framework) +- `service_name` - name of the service or library under test (when you want it to be different for a test framework) Example usage: @@ -219,7 +219,7 @@ Datadog.configure { |c| c.diagnostics.startup_logs.enabled = false } Switching the library into debug mode will produce verbose, detailed logs about tracing activity, including any suppressed errors. This output can be helpful in identifying errors, confirming trace output, or catching HTTP transport issues. -You can enable this via `DD_TRACE_DEBUG=1` or in the configure block: +You can enable this via `DD_TRACE_DEBUG=1` or in the `Datadog.configure` block: ```ruby Datadog.configure { |c| c.diagnostics.debug = true } diff --git a/docs/UpgradeGuide.md b/docs/UpgradeGuide.md index f0e5bd32..fca60690 100644 --- a/docs/UpgradeGuide.md +++ b/docs/UpgradeGuide.md @@ -1,6 +1,6 @@ # Upgrading from ddtrace 1.x to datadog-ci -Test visibility for Ruby is no longer part of `datadog` gem and fully migrated to +[Test visibility for Ruby](https://docs.datadoghq.com/tests/setup/ruby/) is no longer part of `datadog` gem and fully migrated to `datadog-ci` gem. To continue using it after gem `datadog` v2.0 is released, do these changes. ## Add datadog-ci to your gemfile @@ -31,7 +31,7 @@ end ## Change WebMock or VCR configuration -Test visibility features (such as intelligent test runner, git metadata upload, code coverage support) require some DataDog endpoints to be allowlisted by WebMock/VCR tools when using agentless mode. +New test visibility features (such as [intelligent test runner](https://docs.datadoghq.com/intelligent_test_runner/), git metadata upload, [code coverage support](https://docs.datadoghq.com/tests/code_coverage)) require some DataDog endpoints to be allowlisted by WebMock/VCR tools when using agentless mode. For WebMock allow all requests that match datadoghq: From b1579b23b6f9222347014d48e649517550debf45 Mon Sep 17 00:00:00 2001 From: Andrey Date: Tue, 23 Apr 2024 16:31:54 +0200 Subject: [PATCH 6/6] recommend using ignore_request for VCR config --- README.md | 6 ++++-- docs/UpgradeGuide.md | 8 +++++--- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index ab6c6dc1..f50a5cd0 100644 --- a/README.md +++ b/README.md @@ -200,8 +200,10 @@ VCR.configure do |config| config.ignore_hosts "127.0.0.1", "localhost" # when using agentless mode - # note to use the correct datadog site (e.g. datadoghq.eu, etc) - config.ignore_hosts "citestcycle-intake.datadoghq.com", "api.datadoghq.com", "citestcov-intake.datadoghq.com" + config.ignore_request do |request| + # ignore all requests to datadoghq hosts + request.uri =~ /datadoghq/ + end end ``` diff --git a/docs/UpgradeGuide.md b/docs/UpgradeGuide.md index fca60690..b0634285 100644 --- a/docs/UpgradeGuide.md +++ b/docs/UpgradeGuide.md @@ -39,11 +39,13 @@ For WebMock allow all requests that match datadoghq: WebMock.disable_net_connect!(:allow => /datadoghq/) ``` -For VCR provide a list of Datadog backend hosts as ignored hosts: +For VCR provide `ignore_request` configuration: ```ruby VCR.configure do |config| - # note to use the correct datadog site (e.g. datadoghq.eu, etc) - config.ignore_hosts "citestcycle-intake.datadoghq.com", "api.datadoghq.com", "citestcov-intake.datadoghq.com" + config.ignore_request do |request| + # ignore all requests to datadoghq hosts + request.uri =~ /datadoghq/ + end end ```