Module: Datadog::CI

Defined in:
lib/datadog/ci.rb,
lib/datadog/ci/span.rb,
lib/datadog/ci/test.rb,
lib/datadog/ci/ext/git.rb,
lib/datadog/ci/version.rb,
lib/datadog/ci/ext/test.rb,
lib/datadog/ci/null_span.rb,
lib/datadog/ci/utils/git.rb,
lib/datadog/ci/utils/url.rb,
lib/datadog/ci/test_suite.rb,
lib/datadog/ci/test_module.rb,
lib/datadog/ci/ext/settings.rb,
lib/datadog/ci/test_session.rb,
lib/datadog/ci/ext/app_types.rb,
lib/datadog/ci/ext/transport.rb,
lib/datadog/ci/transport/gzip.rb,
lib/datadog/ci/transport/http.rb,
lib/datadog/ci/utils/test_run.rb,
lib/datadog/ci/concurrent_span.rb,
lib/datadog/ci/ext/environment.rb,
lib/datadog/ci/contrib/settings.rb,
lib/datadog/ci/contrib/rspec/ext.rb,
lib/datadog/ci/transport/api/base.rb,
lib/datadog/ci/contrib/integration.rb,
lib/datadog/ci/contrib/cucumber/ext.rb,
lib/datadog/ci/contrib/minitest/ext.rb,
lib/datadog/ci/contrib/rspec/example.rb,
lib/datadog/ci/contrib/rspec/patcher.rb,
lib/datadog/ci/test_visibility/flush.rb,
lib/datadog/ci/transport/api/builder.rb,
lib/datadog/ci/configuration/settings.rb,
lib/datadog/ci/contrib/minitest/hooks.rb,
lib/datadog/ci/transport/api/evp_proxy.rb,
lib/datadog/ci/configuration/components.rb,
lib/datadog/ci/configuration/extensions.rb,
lib/datadog/ci/contrib/cucumber/patcher.rb,
lib/datadog/ci/contrib/minitest/patcher.rb,
lib/datadog/ci/test_visibility/recorder.rb,
lib/datadog/ci/contrib/rspec/integration.rb,
lib/datadog/ci/ext/environment/extractor.rb,
lib/datadog/ci/ext/environment/providers.rb,
lib/datadog/ci/test_visibility/transport.rb,
lib/datadog/ci/contrib/cucumber/formatter.rb,
lib/datadog/ci/transport/api/ci_test_cycle.rb,
lib/datadog/ci/contrib/cucumber/integration.rb,
lib/datadog/ci/contrib/minitest/integration.rb,
lib/datadog/ci/test_visibility/context/local.rb,
lib/datadog/ci/ext/environment/providers/base.rb,
lib/datadog/ci/test_visibility/context/global.rb,
lib/datadog/ci/ext/environment/providers/azure.rb,
lib/datadog/ci/ext/environment/providers/buddy.rb,
lib/datadog/ci/contrib/cucumber/instrumentation.rb,
lib/datadog/ci/ext/environment/providers/gitlab.rb,
lib/datadog/ci/ext/environment/providers/travis.rb,
lib/datadog/ci/test_visibility/serializers/base.rb,
lib/datadog/ci/test_visibility/serializers/span.rb,
lib/datadog/ci/ext/environment/providers/bitrise.rb,
lib/datadog/ci/ext/environment/providers/jenkins.rb,
lib/datadog/ci/ext/environment/providers/appveyor.rb,
lib/datadog/ci/ext/environment/providers/circleci.rb,
lib/datadog/ci/ext/environment/providers/teamcity.rb,
lib/datadog/ci/ext/environment/providers/bitbucket.rb,
lib/datadog/ci/ext/environment/providers/buildkite.rb,
lib/datadog/ci/ext/environment/providers/codefresh.rb,
lib/datadog/ci/ext/environment/providers/local_git.rb,
lib/datadog/ci/test_visibility/serializers/test_v1.rb,
lib/datadog/ci/test_visibility/serializers/test_v2.rb,
lib/datadog/ci/contrib/rspec/configuration/settings.rb,
lib/datadog/ci/test_visibility/serializers/test_suite.rb,
lib/datadog/ci/contrib/cucumber/configuration/settings.rb,
lib/datadog/ci/contrib/minitest/configuration/settings.rb,
lib/datadog/ci/test_visibility/serializers/test_module.rb,
lib/datadog/ci/ext/environment/providers/github_actions.rb,
lib/datadog/ci/test_visibility/serializers/test_session.rb,
lib/datadog/ci/ext/environment/providers/aws_code_pipeline.rb,
lib/datadog/ci/ext/environment/providers/user_defined_tags.rb,
lib/datadog/ci/test_visibility/serializers/factories/test_level.rb,
lib/datadog/ci/test_visibility/serializers/factories/test_suite_level.rb

Overview

Datadog CI visibility public API.

Defined Under Namespace

Modules: Configuration, Contrib, Ext, TestVisibility, Transport, Utils, VERSION Classes: ConcurrentSpan, NullSpan, Span, Test, TestModule, TestSession, TestSuite

Class Method Summary collapse

Class Method Details

.active_span(span_type) ⇒ Datadog::CI::Span?

The active, unfinished custom span if it matches given type. If no span is active, or if the active span is not a custom span with given type, returns nil.

The active span belongs to an active_test.

Usage:

“‘ # start span Datadog::CI.trace(

"step",
"Given I have 42 cucumbers",
tags: {}

)

# somewhere else, access the active “step” span step_span = Datadog::CI.active_span(“step”) step_span.finish() “‘

Parameters:

  • span_type (String) —

    type of the span to retrieve (for example “step” or “query”) that was provided to trace

Returns:

  • (Datadog::CI::Span) —

    the active span

  • (nil) —

    if no span is active, or if the active span is not a custom span with given type



320
321
322
323
 
# File 'lib/datadog/ci.rb', line 320

def active_span(span_type)
  span = recorder.active_span
  span if span && span.span_type == span_type
end

.active_test ⇒ Datadog::CI::Test?

The active, unfinished test span.

Usage:

“‘ # start a test Datadog::CI.start_test(

"test_add_two_numbers",
"calculator_tests",
service: "my-web-site-tests",
tags: { Datadog::CI::Ext::Test::TAG_FRAMEWORK => "my-test-framework" }

)

# somewhere else, access the active test test_span = Datadog::CI.active_test test_span.passed! test_span.finish “‘

Returns:



346
347
348
 
# File 'lib/datadog/ci.rb', line 346

def active_test
  recorder.active_test
end

.active_test_module ⇒ Datadog::CI::TestModule?

The active, unfinished test module.

Usage:

“‘ # start a test module Datadog::CI.start_test_module(

"my-module",
service: "my-web-site-tests",
tags: { Datadog::CI::Ext::Test::TAG_FRAMEWORK => "my-test-framework" }

)

# somewhere else, access the current module test_module = Datadog::CI.active_test_module test_module.finish “‘

Returns:



117
118
119
 
# File 'lib/datadog/ci.rb', line 117

def active_test_module
  recorder.active_test_module
end

.active_test_session ⇒ Datadog::CI::TestSession?

The active, unfinished test session.

Usage:

“‘ # start a test session Datadog::CI.start_test_session(

service: "my-web-site-tests",
tags: { Datadog::CI::Ext::Test::TAG_FRAMEWORK => "my-test-framework" }

)

# somewhere else, access the session test_session = Datadog::CI.active_test_session test_session.finish “‘

Returns:



61
62
63
 
# File 'lib/datadog/ci.rb', line 61

def active_test_session
  recorder.active_test_session
end

.active_test_suite(test_suite_name) ⇒ Datadog::CI::TestSuite?

The active, unfinished test suite.

Usage:

“‘ # start a test suite Datadog::CI.start_test_suite(

"calculator_tests",
service: "my-web-site-tests",
tags: { Datadog::CI::Ext::Test::TAG_FRAMEWORK => "my-test-framework" }

)

# Somewhere else after the suite has ended test_suite = Datadog::CI.active_test_suite(“calculator_tests”) test_suite.finish “‘

Returns:



170
171
172
 
# File 'lib/datadog/ci.rb', line 170

def active_test_suite(test_suite_name)
  recorder.active_test_suite(test_suite_name)
end

.deactivate_test(test) ⇒ Object

Internal only, to finish a test use Datadog::CI::Test#finish



352
353
354
 
# File 'lib/datadog/ci.rb', line 352

def deactivate_test(test)
  recorder.deactivate_test(test)
end

.deactivate_test_module ⇒ Object

Internal only, to finish a test module use Datadog::CI::TestModule#finish



364
365
366
 
# File 'lib/datadog/ci.rb', line 364

def deactivate_test_module
  recorder.deactivate_test_module
end

.deactivate_test_session ⇒ Object

Internal only, to finish a test session use Datadog::CI::TestSession#finish



358
359
360
 
# File 'lib/datadog/ci.rb', line 358

def deactivate_test_session
  recorder.deactivate_test_session
end

.deactivate_test_suite(test_suite_name) ⇒ Object

Internal only, to finish a test suite use Datadog::CI::TestSuite#finish



370
371
372
 
# File 'lib/datadog/ci.rb', line 370

def deactivate_test_suite(test_suite_name)
  recorder.deactivate_test_suite(test_suite_name)
end

.start_test(test_name, test_suite_name, service: nil, tags: {}) ⇒ Datadog::CI::Test, Datadog::CI::NullSpan

Same as trace_test but it does not accept a block. Raises an error if a test is already active.

Usage:

“‘ ci_test = Datadog::CI.start_test(

"test_add_two_numbers",
"calculator_tests",
service: "my-web-site-tests",
tags: { Datadog::CI::Ext::Test::TAG_FRAMEWORK => "my-test-framework" }

) # … run test here … ci_test.finish “‘

Parameters:

  • test_name (String) —

    Test name (example: “test_add_two_numbers”).

  • test_suite_name (String) —

    name of test suite this test belongs to (example: “CalculatorTest”).

  • service (String) (defaults to: nil) —

    the service name for this span (optional, inherited from test session if not provided)

  • tags (Hash<String,String>) (defaults to: {}) —

    extra tags which should be added to the test.

Returns:



250
251
252
 
# File 'lib/datadog/ci.rb', line 250

def start_test(test_name, test_suite_name, service: nil, tags: {})
  recorder.trace_test(test_name, test_suite_name, service: service, tags: tags)
end

.start_test_module(test_module_name, service: nil, tags: {}) ⇒ Datadog::CI::TestModule, Datadog::CI::NullSpan

Starts a ci_test_module that represents a single test module (for most Ruby test frameworks module will correspond 1-1 to the test session).

Read Datadog documentation on test modules [here](docs.datadoghq.com/continuous_integration/explorer/?tab=testruns#module).

Returns the existing test session if one is already active. There is at most a single test module per process active at any given time.

The start_test_module method is used to mark the start of the test session: “‘ Datadog::CI.start_test_module(

"my-module",
service: "my-web-site-tests",
tags: { Datadog::CI::Ext::Test::TAG_FRAMEWORK => "my-test-framework" }

)

# Somewhere else after the module has ended Datadog::CI.active_test_module.finish “‘

Remember that calling Datadog::CI::TestModule#finish is mandatory.

Parameters:

  • test_module_name (String) —

    the name for this module

  • service (String) (defaults to: nil) —

    the service name for this session (optional, inherited from test session if not provided)

  • tags (Hash<String,String>) (defaults to: {}) —

    extra tags which should be added to the test module (optional, some tags are inherited from test session).

Returns:



94
95
96
 
# File 'lib/datadog/ci.rb', line 94

def start_test_module(test_module_name, service: nil, tags: {})
  recorder.start_test_module(test_module_name, service: service, tags: tags)
end

.start_test_session(service: nil, tags: {}) ⇒ Datadog::CI::TestSession, Datadog::CI::NullSpan

Starts a ci_test_session that represents the whole test session run.

Read Datadog documentation on test sessions [here](docs.datadoghq.com/continuous_integration/explorer/?tab=testruns#sessions).

Returns the existing test session if one is already active. There is at most a single test session per process.

The start_test_session method is used to mark the start of the test session: “‘ Datadog::CI.start_test_session(

service: "my-web-site-tests",
tags: { Datadog::CI::Ext::Test::TAG_FRAMEWORK => "my-test-framework" }

)

# Somewhere else after test run has ended Datadog::CI.active_test_session.finish “‘

Remember that calling Datadog::CI::TestSession#finish is mandatory.

Parameters:

  • service (String) (defaults to: nil) —

    the service name for this session (optional, defaults to DD_SERVICE)

  • tags (Hash<String,String>) (defaults to: {}) —

    extra tags which should be added to the test session.

Returns:



38
39
40
41
 
# File 'lib/datadog/ci.rb', line 38

def start_test_session(service: nil, tags: {})
  service ||= Datadog.configuration.service
  recorder.start_test_session(service: service, tags: tags)
end

.start_test_suite(test_suite_name, service: nil, tags: {}) ⇒ Datadog::CI::TestSuite, Datadog::CI::NullSpan

Starts a ci_test_suite that represents a single test suite. If a test suite with given name is running, returns the existing test suite.

Read Datadog documentation on test suites [here](docs.datadoghq.com/continuous_integration/explorer/?tab=testruns#module).

The start_test_suite method is used to mark the start of a test suite: “‘ Datadog::CI.start_test_suite(

"calculator_tests",
service: "my-web-site-tests",
tags: { Datadog::CI::Ext::Test::TAG_FRAMEWORK => "my-test-framework" }

)

# Somewhere else after the suite has ended Datadog::CI.active_test_suite(“calculator_tests”).finish “‘

Remember that calling Datadog::CI::TestSuite#finish is mandatory.

Parameters:

  • test_suite_name (String) —

    the name of the test suite

  • service (String) (defaults to: nil) —

    the service name for this test suite (optional, inherited from test session if not provided)

  • tags (Hash<String,String>) (defaults to: {}) —

    extra tags which should be added to the test module (optional, some tags are inherited from test session)

Returns:



147
148
149
 
# File 'lib/datadog/ci.rb', line 147

def start_test_suite(test_suite_name, service: nil, tags: {})
  recorder.start_test_suite(test_suite_name, service: service, tags: tags)
end

.trace(span_type, span_name, tags: {}) {|ci_span, ci_span| ... } ⇒ Object, ...

Trace any custom span inside a test. For example, you could trace:

  • cucumber step

  • database query

  • any custom operation you want to see in your trace view

You can use this method with a do-block like:

“‘ Datadog::CI.trace(

"step",
"Given I have 42 cucumbers",
tags: {}

) do

run_operation

end “‘

The trace method can also be used without a block in this way: “‘ ci_span = Datadog::CI.trace(

"step",
"Given I have 42 cucumbers",
tags: {}

) # … run test here … ci_span.finish “‘ Remember that in this case, calling Datadog::CI::Span#finish is mandatory.

Parameters:

  • span_type (String) —

    custom, user-defined span type (for example “step” or “query”).

  • span_name (String) —

    the resource this span refers, or ‘test` if it’s missing

  • tags (Hash<String,String>) (defaults to: {}) —

    extra tags which should be added to the span.

Yields:

  • Optional block where newly created Span captures the execution.

Yield Parameters:

Returns:

  • (Object) —

    If a block is provided, returns the result of the block execution.

  • (Datadog::CI::Span) —

    If no block is provided, returns the active, unfinished Span.

  • (Datadog::CI::NullSpan) —

    ci_span null object if CI visibility is disabled



293
294
295
 
# File 'lib/datadog/ci.rb', line 293

def trace(span_type, span_name, tags: {}, &block)
  recorder.trace(span_type, span_name, tags: tags, &block)
end

.trace_test(test_name, test_suite_name, service: nil, tags: {}) {|ci_test, ci_span| ... } ⇒ Object, ...

Return a ci_test that will trace a test called ‘test_name`. Raises an error if a test is already active. If there is an active test session, the new test will be connected to the session. The test will inherit service name and tags from the running test session if not provided in parameters.

You could trace your test using a do-block like:

“‘ Datadog::CI.trace_test(

"test_add_two_numbers",
"calculator_tests",
service: "my-web-site-tests",
tags: { Datadog::CI::Ext::Test::TAG_FRAMEWORK => "my-test-framework" }

) do |ci_test|

result = run_test

if result.ok?
  ci_test.passed!
else
  ci_test.failed!(exception: result.exception)
end

end “‘

The trace_test method can also be used without a block in this way: “‘ ci_test = Datadog::CI.trace_test(

"test_add_two_numbers",
"calculator_tests",
service: "my-web-site-tests",
tags: { Datadog::CI::Ext::Test::TAG_FRAMEWORK => "my-test-framework" }

) # … run test here … ci_test.finish “‘

Remember that in this case, calling Datadog::CI::Test#finish is mandatory.

Parameters:

  • test_name (String) —

    Test name (example: “test_add_two_numbers”).

  • test_suite_name (String) —

    name of test suite this test belongs to (example: “CalculatorTest”).

  • service (String) (defaults to: nil) —

    the service name for this test (optional, inherited from test session if not provided)

  • tags (Hash<String,String>) (defaults to: {}) —

    extra tags which should be added to the test.

Yields:

  • Optional block where newly created Test captures the execution.

Yield Parameters:

Returns:

  • (Object) —

    If a block is provided, returns the result of the block execution.

  • (Datadog::CI::Test) —

    If no block is provided, returns the active, unfinished Test.

  • (Datadog::CI::NullSpan) —

    ci_span null object if CI visibility is disabled



224
225
226
 
# File 'lib/datadog/ci.rb', line 224

def trace_test(test_name, test_suite_name, service: nil, tags: {}, &block)
  recorder.trace_test(test_name, test_suite_name, service: service, tags: tags, &block)
end