ddtrace 0.13.0 → 0.47.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.circleci/config.yml +598 -381
- data/.circleci/images/primary/Dockerfile-2.0.0 +6 -2
- data/.circleci/images/primary/Dockerfile-2.1.10 +6 -2
- data/.circleci/images/primary/Dockerfile-2.2.10 +6 -2
- data/.circleci/images/primary/Dockerfile-2.3.8 +75 -0
- data/.circleci/images/primary/Dockerfile-2.4.6 +73 -0
- data/.circleci/images/primary/{Dockerfile-2.3.7 → Dockerfile-2.5.6} +2 -2
- data/.circleci/images/primary/{Dockerfile-2.4.4 → Dockerfile-2.6.4} +2 -2
- data/.circleci/images/primary/Dockerfile-2.7.0 +73 -0
- data/.circleci/images/primary/Dockerfile-3.0.0 +73 -0
- data/.circleci/images/primary/Dockerfile-jruby-9.2-latest +78 -0
- data/.circleci/images/primary/Dockerfile-jruby-9.2.0.0 +73 -0
- data/.circleci/images/primary/{Dockerfile-1.9.3 → Dockerfile-truffleruby-21.0.0} +6 -2
- data/.env +5 -2
- data/.github/CODEOWNERS +1 -0
- data/.github/workflows/add-milestone-to-pull-requests.yml +42 -0
- data/.github/workflows/create-next-milestone.yml +20 -0
- data/.gitignore +2 -0
- data/.gitlab-ci.yml +27 -0
- data/.rubocop.yml +270 -6
- data/.rubocop_todo.yml +397 -0
- data/.simplecov +47 -0
- data/Appraisals +933 -127
- data/CHANGELOG.md +2106 -97
- data/CONTRIBUTING.md +85 -0
- data/Gemfile +55 -2
- data/LICENSE +4 -22
- data/LICENSE-3rdparty.csv +2 -0
- data/LICENSE.Apache +200 -0
- data/LICENSE.BSD3 +24 -0
- data/NOTICE +4 -0
- data/README.md +5 -34
- data/Rakefile +825 -351
- data/benchmarks/postgres_database.yml +9 -0
- data/benchmarks/sidekiq_test.rb +154 -0
- data/ddtrace.gemspec +8 -17
- data/docker-compose.yml +260 -47
- data/docs/DevelopmentGuide.md +249 -0
- data/docs/GettingStarted.md +1435 -290
- data/integration/README.md +68 -0
- data/integration/apps/rack/.dockerignore +1 -0
- data/integration/apps/rack/.envrc.sample +1 -0
- data/integration/apps/rack/.gitignore +4 -0
- data/integration/apps/rack/.rspec +1 -0
- data/integration/apps/rack/Dockerfile +25 -0
- data/integration/apps/rack/Dockerfile-ci +11 -0
- data/integration/apps/rack/Gemfile +24 -0
- data/integration/apps/rack/README.md +93 -0
- data/integration/apps/rack/app/acme.rb +80 -0
- data/integration/apps/rack/app/datadog.rb +17 -0
- data/integration/apps/rack/bin/run +22 -0
- data/integration/apps/rack/bin/setup +17 -0
- data/integration/apps/rack/bin/test +24 -0
- data/integration/apps/rack/config.ru +6 -0
- data/integration/apps/rack/config/puma.rb +14 -0
- data/integration/apps/rack/config/unicorn.rb +23 -0
- data/integration/apps/rack/docker-compose.ci.yml +62 -0
- data/integration/apps/rack/docker-compose.yml +78 -0
- data/integration/apps/rack/script/build-images +38 -0
- data/integration/apps/rack/script/ci +50 -0
- data/integration/apps/rack/spec/integration/basic_spec.rb +10 -0
- data/integration/apps/rack/spec/spec_helper.rb +16 -0
- data/integration/apps/rack/spec/support/integration_helper.rb +22 -0
- data/integration/apps/rails-five/.dockerignore +1 -0
- data/integration/apps/rails-five/.env +3 -0
- data/integration/apps/rails-five/.envrc.sample +1 -0
- data/integration/apps/rails-five/.gitignore +30 -0
- data/integration/apps/rails-five/Dockerfile +25 -0
- data/integration/apps/rails-five/Dockerfile-ci +11 -0
- data/integration/apps/rails-five/Gemfile +104 -0
- data/integration/apps/rails-five/README.md +94 -0
- data/integration/apps/rails-five/Rakefile +6 -0
- data/integration/apps/rails-five/app/channels/application_cable/channel.rb +4 -0
- data/integration/apps/rails-five/app/channels/application_cable/connection.rb +4 -0
- data/integration/apps/rails-five/app/controllers/application_controller.rb +2 -0
- data/integration/apps/rails-five/app/controllers/basic_controller.rb +36 -0
- data/integration/apps/rails-five/app/controllers/concerns/.keep +0 -0
- data/integration/apps/rails-five/app/controllers/health_controller.rb +9 -0
- data/integration/apps/rails-five/app/controllers/jobs_controller.rb +12 -0
- data/integration/apps/rails-five/app/jobs/application_job.rb +2 -0
- data/integration/apps/rails-five/app/jobs/test_job.rb +12 -0
- data/integration/apps/rails-five/app/mailers/application_mailer.rb +4 -0
- data/integration/apps/rails-five/app/models/application_record.rb +3 -0
- data/integration/apps/rails-five/app/models/concerns/.keep +0 -0
- data/integration/apps/rails-five/app/models/test.rb +2 -0
- data/integration/apps/rails-five/app/views/layouts/mailer.html.erb +13 -0
- data/integration/apps/rails-five/app/views/layouts/mailer.text.erb +1 -0
- data/integration/apps/rails-five/bin/bundle +3 -0
- data/integration/apps/rails-five/bin/rails +9 -0
- data/integration/apps/rails-five/bin/rake +9 -0
- data/integration/apps/rails-five/bin/run +24 -0
- data/integration/apps/rails-five/bin/setup +27 -0
- data/integration/apps/rails-five/bin/spring +17 -0
- data/integration/apps/rails-five/bin/test +21 -0
- data/integration/apps/rails-five/bin/update +28 -0
- data/integration/apps/rails-five/config.ru +5 -0
- data/integration/apps/rails-five/config/application.rb +97 -0
- data/integration/apps/rails-five/config/boot.rb +4 -0
- data/integration/apps/rails-five/config/cable.yml +10 -0
- data/integration/apps/rails-five/config/credentials.yml.enc +1 -0
- data/integration/apps/rails-five/config/database.yml +28 -0
- data/integration/apps/rails-five/config/environment.rb +5 -0
- data/integration/apps/rails-five/config/environments/development.rb +51 -0
- data/integration/apps/rails-five/config/environments/production.rb +82 -0
- data/integration/apps/rails-five/config/environments/test.rb +43 -0
- data/integration/apps/rails-five/config/initializers/datadog.rb +18 -0
- data/integration/apps/rails-five/config/initializers/filter_parameter_logging.rb +4 -0
- data/integration/apps/rails-five/config/initializers/resque.rb +4 -0
- data/integration/apps/rails-five/config/initializers/rollbar.rb +5 -0
- data/integration/apps/rails-five/config/initializers/wrap_parameters.rb +14 -0
- data/integration/apps/rails-five/config/locales/en.yml +33 -0
- data/integration/apps/rails-five/config/puma.rb +24 -0
- data/integration/apps/rails-five/config/routes.rb +11 -0
- data/integration/apps/rails-five/config/spring.rb +6 -0
- data/integration/apps/rails-five/config/unicorn.rb +29 -0
- data/integration/apps/rails-five/db/migrate/20190927215052_create_tests.rb +11 -0
- data/integration/apps/rails-five/db/schema.rb +23 -0
- data/integration/apps/rails-five/db/seeds.rb +7 -0
- data/integration/apps/rails-five/docker-compose.ci.yml +98 -0
- data/integration/apps/rails-five/docker-compose.yml +100 -0
- data/integration/apps/rails-five/lib/tasks/.keep +0 -0
- data/integration/apps/rails-five/log/.keep +0 -0
- data/integration/apps/rails-five/public/robots.txt +1 -0
- data/integration/apps/rails-five/script/build-images +35 -0
- data/integration/apps/rails-five/script/ci +50 -0
- data/integration/apps/rails-five/spec/integration/basic_spec.rb +10 -0
- data/integration/apps/rails-five/spec/spec_helper.rb +16 -0
- data/integration/apps/rails-five/spec/support/integration_helper.rb +22 -0
- data/integration/apps/rails-five/storage/.keep +0 -0
- data/integration/apps/rails-five/tmp/.keep +0 -0
- data/integration/apps/rails-five/vendor/.keep +0 -0
- data/integration/apps/ruby/.dockerignore +1 -0
- data/integration/apps/ruby/.envrc.sample +1 -0
- data/integration/apps/ruby/.gitignore +2 -0
- data/integration/apps/ruby/Dockerfile +25 -0
- data/integration/apps/ruby/Dockerfile-ci +11 -0
- data/integration/apps/ruby/Gemfile +11 -0
- data/integration/apps/ruby/README.md +70 -0
- data/integration/apps/ruby/agent.yaml +3 -0
- data/integration/apps/ruby/app/datadog.rb +13 -0
- data/integration/apps/ruby/app/fibonacci.rb +58 -0
- data/integration/apps/ruby/bin/run +20 -0
- data/integration/apps/ruby/bin/setup +17 -0
- data/integration/apps/ruby/bin/test +21 -0
- data/integration/apps/ruby/docker-compose.ci.yml +51 -0
- data/integration/apps/ruby/docker-compose.yml +63 -0
- data/integration/apps/ruby/script/build-images +38 -0
- data/integration/apps/ruby/script/ci +50 -0
- data/integration/images/agent/Dockerfile +2 -0
- data/integration/images/agent/agent.yaml +3 -0
- data/integration/images/include/datadog/analyzer.rb +71 -0
- data/integration/images/include/datadog/demo_env.rb +101 -0
- data/integration/images/include/http-health-check +33 -0
- data/integration/images/ruby/2.0/Dockerfile +54 -0
- data/integration/images/ruby/2.1/Dockerfile +54 -0
- data/integration/images/ruby/2.2/Dockerfile +54 -0
- data/integration/images/ruby/2.3/Dockerfile +70 -0
- data/integration/images/ruby/2.4/Dockerfile +54 -0
- data/integration/images/ruby/2.5/Dockerfile +54 -0
- data/integration/images/ruby/2.6/Dockerfile +54 -0
- data/integration/images/ruby/2.7/Dockerfile +54 -0
- data/integration/images/ruby/3.0/Dockerfile +54 -0
- data/integration/images/wrk/Dockerfile +33 -0
- data/integration/images/wrk/scripts/entrypoint.sh +17 -0
- data/integration/images/wrk/scripts/scenarios/basic/default.lua +1 -0
- data/integration/images/wrk/scripts/scenarios/basic/fibonacci.lua +1 -0
- data/integration/script/build-images +43 -0
- data/lib/ddtrace.rb +65 -62
- data/lib/ddtrace/analytics.rb +38 -0
- data/lib/ddtrace/auto_instrument.rb +3 -0
- data/lib/ddtrace/auto_instrument_base.rb +6 -0
- data/lib/ddtrace/buffer.rb +298 -32
- data/lib/ddtrace/chunker.rb +34 -0
- data/lib/ddtrace/configuration.rb +151 -26
- data/lib/ddtrace/configuration/base.rb +84 -0
- data/lib/ddtrace/configuration/components.rb +151 -0
- data/lib/ddtrace/configuration/{resolver.rb → dependency_resolver.rb} +2 -2
- data/lib/ddtrace/configuration/option.rb +64 -0
- data/lib/ddtrace/configuration/option_definition.rb +121 -0
- data/lib/ddtrace/configuration/option_definition_set.rb +18 -0
- data/lib/ddtrace/configuration/option_set.rb +6 -0
- data/lib/ddtrace/configuration/options.rb +111 -0
- data/lib/ddtrace/configuration/pin_setup.rb +4 -3
- data/lib/ddtrace/configuration/settings.rb +299 -0
- data/lib/ddtrace/context.rb +133 -66
- data/lib/ddtrace/context_flush.rb +51 -114
- data/lib/ddtrace/context_provider.rb +61 -0
- data/lib/ddtrace/contrib/action_cable/configuration/settings.rb +30 -0
- data/lib/ddtrace/contrib/action_cable/event.rb +66 -0
- data/lib/ddtrace/contrib/action_cable/events.rb +33 -0
- data/lib/ddtrace/contrib/action_cable/events/broadcast.rb +49 -0
- data/lib/ddtrace/contrib/action_cable/events/perform_action.rb +55 -0
- data/lib/ddtrace/contrib/action_cable/events/transmit.rb +50 -0
- data/lib/ddtrace/contrib/action_cable/ext.rb +26 -0
- data/lib/ddtrace/contrib/action_cable/instrumentation.rb +31 -0
- data/lib/ddtrace/contrib/action_cable/integration.rb +45 -0
- data/lib/ddtrace/contrib/action_cable/patcher.rb +27 -0
- data/lib/ddtrace/contrib/action_pack/action_controller/instrumentation.rb +146 -0
- data/lib/ddtrace/contrib/action_pack/action_controller/patcher.rb +25 -0
- data/lib/ddtrace/contrib/action_pack/configuration/settings.rb +32 -0
- data/lib/ddtrace/contrib/action_pack/ext.rb +19 -0
- data/lib/ddtrace/contrib/action_pack/integration.rb +45 -0
- data/lib/ddtrace/contrib/action_pack/patcher.rb +23 -0
- data/lib/ddtrace/contrib/action_pack/utils.rb +36 -0
- data/lib/ddtrace/contrib/action_view/configuration/settings.rb +31 -0
- data/lib/ddtrace/contrib/action_view/event.rb +35 -0
- data/lib/ddtrace/contrib/action_view/events.rb +30 -0
- data/lib/ddtrace/contrib/action_view/events/render_partial.rb +46 -0
- data/lib/ddtrace/contrib/action_view/events/render_template.rb +49 -0
- data/lib/ddtrace/contrib/action_view/ext.rb +20 -0
- data/lib/ddtrace/contrib/action_view/instrumentation/partial_renderer.rb +74 -0
- data/lib/ddtrace/contrib/action_view/instrumentation/template_renderer.rb +167 -0
- data/lib/ddtrace/contrib/action_view/integration.rb +52 -0
- data/lib/ddtrace/contrib/action_view/patcher.rb +47 -0
- data/lib/ddtrace/contrib/action_view/utils.rb +32 -0
- data/lib/ddtrace/contrib/active_model_serializers/configuration/settings.rb +30 -0
- data/lib/ddtrace/contrib/active_model_serializers/event.rb +14 -3
- data/lib/ddtrace/contrib/active_model_serializers/events/render.rb +2 -2
- data/lib/ddtrace/contrib/active_model_serializers/events/serialize.rb +2 -2
- data/lib/ddtrace/contrib/active_model_serializers/ext.rb +20 -0
- data/lib/ddtrace/contrib/active_model_serializers/integration.rb +40 -0
- data/lib/ddtrace/contrib/active_model_serializers/patcher.rb +12 -45
- data/lib/ddtrace/contrib/active_record/configuration/resolver.rb +128 -0
- data/lib/ddtrace/contrib/active_record/configuration/settings.rb +35 -0
- data/lib/ddtrace/contrib/active_record/event.rb +1 -1
- data/lib/ddtrace/contrib/active_record/events/instantiation.rb +17 -8
- data/lib/ddtrace/contrib/active_record/events/sql.rb +32 -12
- data/lib/ddtrace/contrib/active_record/ext.rb +24 -0
- data/lib/ddtrace/contrib/active_record/integration.rb +53 -0
- data/lib/ddtrace/contrib/active_record/patcher.rb +5 -35
- data/lib/ddtrace/contrib/active_record/utils.rb +85 -31
- data/lib/ddtrace/contrib/active_support/cache/instrumentation.rb +258 -0
- data/lib/ddtrace/contrib/active_support/cache/patcher.rb +69 -0
- data/lib/ddtrace/contrib/active_support/cache/redis.rb +47 -0
- data/lib/ddtrace/contrib/active_support/configuration/settings.rb +30 -0
- data/lib/ddtrace/contrib/active_support/ext.rb +27 -0
- data/lib/ddtrace/contrib/active_support/integration.rb +46 -0
- data/lib/ddtrace/contrib/active_support/notifications/event.rb +15 -2
- data/lib/ddtrace/contrib/active_support/notifications/subscriber.rb +3 -2
- data/lib/ddtrace/contrib/active_support/notifications/subscription.rb +20 -12
- data/lib/ddtrace/contrib/active_support/patcher.rb +23 -0
- data/lib/ddtrace/contrib/analytics.rb +24 -0
- data/lib/ddtrace/contrib/auto_instrument.rb +49 -0
- data/lib/ddtrace/contrib/aws/configuration/settings.rb +30 -0
- data/lib/ddtrace/contrib/aws/ext.rb +23 -0
- data/lib/ddtrace/contrib/aws/instrumentation.rb +37 -19
- data/lib/ddtrace/contrib/aws/integration.rb +42 -0
- data/lib/ddtrace/contrib/aws/patcher.rb +30 -40
- data/lib/ddtrace/contrib/aws/services.rb +3 -0
- data/lib/ddtrace/contrib/concurrent_ruby/configuration/settings.rb +20 -0
- data/lib/ddtrace/contrib/concurrent_ruby/context_composite_executor_service.rb +41 -0
- data/lib/ddtrace/contrib/concurrent_ruby/ext.rb +12 -0
- data/lib/ddtrace/contrib/concurrent_ruby/future_patch.rb +23 -0
- data/lib/ddtrace/contrib/concurrent_ruby/integration.rb +38 -0
- data/lib/ddtrace/contrib/concurrent_ruby/patcher.rb +28 -0
- data/lib/ddtrace/contrib/configurable.rb +102 -0
- data/lib/ddtrace/contrib/configuration/resolver.rb +81 -0
- data/lib/ddtrace/contrib/configuration/resolvers/pattern_resolver.rb +39 -0
- data/lib/ddtrace/contrib/configuration/settings.rb +55 -0
- data/lib/ddtrace/contrib/cucumber/configuration/settings.rb +28 -0
- data/lib/ddtrace/contrib/cucumber/ext.rb +17 -0
- data/lib/ddtrace/contrib/cucumber/formatter.rb +98 -0
- data/lib/ddtrace/contrib/cucumber/instrumentation.rb +24 -0
- data/lib/ddtrace/contrib/cucumber/integration.rb +45 -0
- data/lib/ddtrace/contrib/cucumber/patcher.rb +23 -0
- data/lib/ddtrace/contrib/dalli/configuration/settings.rb +30 -0
- data/lib/ddtrace/contrib/dalli/ext.rb +20 -0
- data/lib/ddtrace/contrib/dalli/instrumentation.rb +36 -17
- data/lib/ddtrace/contrib/dalli/integration.rb +38 -0
- data/lib/ddtrace/contrib/dalli/patcher.rb +13 -41
- data/lib/ddtrace/contrib/dalli/quantize.rb +4 -4
- data/lib/ddtrace/contrib/delayed_job/configuration/settings.rb +32 -0
- data/lib/ddtrace/contrib/delayed_job/ext.rb +23 -0
- data/lib/ddtrace/contrib/delayed_job/integration.rb +38 -0
- data/lib/ddtrace/contrib/delayed_job/patcher.rb +28 -0
- data/lib/ddtrace/contrib/delayed_job/plugin.rb +84 -0
- data/lib/ddtrace/contrib/elasticsearch/configuration/settings.rb +31 -0
- data/lib/ddtrace/contrib/elasticsearch/ext.rb +22 -0
- data/lib/ddtrace/contrib/elasticsearch/integration.rb +39 -0
- data/lib/ddtrace/contrib/elasticsearch/patcher.rb +49 -50
- data/lib/ddtrace/contrib/elasticsearch/quantize.rb +3 -2
- data/lib/ddtrace/contrib/ethon/configuration/settings.rb +32 -0
- data/lib/ddtrace/contrib/ethon/easy_patch.rb +151 -0
- data/lib/ddtrace/contrib/ethon/ext.rb +19 -0
- data/lib/ddtrace/contrib/ethon/integration.rb +43 -0
- data/lib/ddtrace/contrib/ethon/multi_patch.rb +84 -0
- data/lib/ddtrace/contrib/ethon/patcher.rb +25 -0
- data/lib/ddtrace/contrib/excon/configuration/settings.rb +33 -0
- data/lib/ddtrace/contrib/excon/ext.rb +17 -0
- data/lib/ddtrace/contrib/excon/integration.rb +43 -0
- data/lib/ddtrace/contrib/excon/middleware.rb +47 -23
- data/lib/ddtrace/contrib/excon/patcher.rb +7 -30
- data/lib/ddtrace/contrib/extensions.rb +143 -0
- data/lib/ddtrace/contrib/faraday/configuration/settings.rb +38 -0
- data/lib/ddtrace/contrib/faraday/connection.rb +18 -0
- data/lib/ddtrace/contrib/faraday/ext.rb +17 -0
- data/lib/ddtrace/contrib/faraday/integration.rb +43 -0
- data/lib/ddtrace/contrib/faraday/middleware.rb +46 -29
- data/lib/ddtrace/contrib/faraday/patcher.rb +36 -56
- data/lib/ddtrace/contrib/faraday/rack_builder.rb +18 -0
- data/lib/ddtrace/contrib/grape/configuration/settings.rb +38 -0
- data/lib/ddtrace/contrib/grape/endpoint.rb +192 -120
- data/lib/ddtrace/contrib/grape/ext.rb +23 -0
- data/lib/ddtrace/contrib/grape/instrumentation.rb +33 -0
- data/lib/ddtrace/contrib/grape/integration.rb +39 -0
- data/lib/ddtrace/contrib/grape/patcher.rb +15 -59
- data/lib/ddtrace/contrib/graphql/configuration/settings.rb +32 -0
- data/lib/ddtrace/contrib/graphql/ext.rb +16 -0
- data/lib/ddtrace/contrib/graphql/integration.rb +39 -0
- data/lib/ddtrace/contrib/graphql/patcher.rb +37 -34
- data/lib/ddtrace/contrib/grpc/configuration/settings.rb +30 -0
- data/lib/ddtrace/contrib/grpc/datadog_interceptor.rb +36 -27
- data/lib/ddtrace/contrib/grpc/datadog_interceptor/client.rb +17 -8
- data/lib/ddtrace/contrib/grpc/datadog_interceptor/server.rb +20 -5
- data/lib/ddtrace/contrib/grpc/ext.rb +18 -0
- data/lib/ddtrace/contrib/grpc/integration.rb +38 -0
- data/lib/ddtrace/contrib/grpc/patcher.rb +8 -38
- data/lib/ddtrace/contrib/http/circuit_breaker.rb +37 -0
- data/lib/ddtrace/contrib/http/configuration/settings.rb +32 -0
- data/lib/ddtrace/contrib/http/ext.rb +17 -0
- data/lib/ddtrace/contrib/http/instrumentation.rb +179 -0
- data/lib/ddtrace/contrib/http/integration.rb +45 -0
- data/lib/ddtrace/contrib/http/patcher.rb +9 -144
- data/lib/ddtrace/contrib/http_annotation_helper.rb +10 -0
- data/lib/ddtrace/contrib/httpclient/configuration/settings.rb +32 -0
- data/lib/ddtrace/contrib/httpclient/ext.rb +17 -0
- data/lib/ddtrace/contrib/httpclient/instrumentation.rb +147 -0
- data/lib/ddtrace/contrib/httpclient/integration.rb +43 -0
- data/lib/ddtrace/contrib/httpclient/patcher.rb +38 -0
- data/lib/ddtrace/contrib/httprb/configuration/settings.rb +32 -0
- data/lib/ddtrace/contrib/httprb/ext.rb +17 -0
- data/lib/ddtrace/contrib/httprb/instrumentation.rb +157 -0
- data/lib/ddtrace/contrib/httprb/integration.rb +43 -0
- data/lib/ddtrace/contrib/httprb/patcher.rb +38 -0
- data/lib/ddtrace/contrib/integration.rb +16 -0
- data/lib/ddtrace/contrib/kafka/configuration/settings.rb +30 -0
- data/lib/ddtrace/contrib/kafka/consumer_event.rb +14 -0
- data/lib/ddtrace/contrib/kafka/consumer_group_event.rb +14 -0
- data/lib/ddtrace/contrib/kafka/event.rb +51 -0
- data/lib/ddtrace/contrib/kafka/events.rb +44 -0
- data/lib/ddtrace/contrib/kafka/events/connection/request.rb +34 -0
- data/lib/ddtrace/contrib/kafka/events/consumer/process_batch.rb +41 -0
- data/lib/ddtrace/contrib/kafka/events/consumer/process_message.rb +39 -0
- data/lib/ddtrace/contrib/kafka/events/consumer_group/heartbeat.rb +39 -0
- data/lib/ddtrace/contrib/kafka/events/consumer_group/join_group.rb +29 -0
- data/lib/ddtrace/contrib/kafka/events/consumer_group/leave_group.rb +29 -0
- data/lib/ddtrace/contrib/kafka/events/consumer_group/sync_group.rb +29 -0
- data/lib/ddtrace/contrib/kafka/events/produce_operation/send_messages.rb +32 -0
- data/lib/ddtrace/contrib/kafka/events/producer/deliver_messages.rb +35 -0
- data/lib/ddtrace/contrib/kafka/ext.rb +41 -0
- data/lib/ddtrace/contrib/kafka/integration.rb +39 -0
- data/lib/ddtrace/contrib/kafka/patcher.rb +26 -0
- data/lib/ddtrace/contrib/mongodb/configuration/settings.rb +33 -0
- data/lib/ddtrace/contrib/mongodb/ext.rb +23 -0
- data/lib/ddtrace/contrib/mongodb/instrumentation.rb +69 -0
- data/lib/ddtrace/contrib/mongodb/integration.rb +38 -0
- data/lib/ddtrace/contrib/mongodb/patcher.rb +11 -74
- data/lib/ddtrace/contrib/mongodb/subscribers.rb +57 -18
- data/lib/ddtrace/contrib/mysql2/configuration/settings.rb +30 -0
- data/lib/ddtrace/contrib/mysql2/ext.rb +18 -0
- data/lib/ddtrace/contrib/mysql2/instrumentation.rb +64 -0
- data/lib/ddtrace/contrib/mysql2/integration.rb +38 -0
- data/lib/ddtrace/contrib/mysql2/patcher.rb +9 -25
- data/lib/ddtrace/contrib/patchable.rb +70 -0
- data/lib/ddtrace/contrib/patcher.rb +65 -0
- data/lib/ddtrace/contrib/presto/configuration/settings.rb +30 -0
- data/lib/ddtrace/contrib/presto/ext.rb +28 -0
- data/lib/ddtrace/contrib/presto/instrumentation.rb +110 -0
- data/lib/ddtrace/contrib/presto/integration.rb +38 -0
- data/lib/ddtrace/contrib/presto/patcher.rb +33 -0
- data/lib/ddtrace/contrib/qless/configuration/settings.rb +35 -0
- data/lib/ddtrace/contrib/qless/ext.rb +20 -0
- data/lib/ddtrace/contrib/qless/integration.rb +38 -0
- data/lib/ddtrace/contrib/qless/patcher.rb +35 -0
- data/lib/ddtrace/contrib/qless/qless_job.rb +73 -0
- data/lib/ddtrace/contrib/qless/tracer_cleaner.rb +33 -0
- data/lib/ddtrace/contrib/que/configuration/settings.rb +43 -0
- data/lib/ddtrace/contrib/que/ext.rb +30 -0
- data/lib/ddtrace/contrib/que/integration.rb +42 -0
- data/lib/ddtrace/contrib/que/patcher.rb +24 -0
- data/lib/ddtrace/contrib/que/tracer.rb +57 -0
- data/lib/ddtrace/contrib/racecar/configuration/settings.rb +30 -0
- data/lib/ddtrace/contrib/racecar/event.rb +22 -7
- data/lib/ddtrace/contrib/racecar/events.rb +2 -0
- data/lib/ddtrace/contrib/racecar/events/batch.rb +2 -2
- data/lib/ddtrace/contrib/racecar/events/consume.rb +27 -0
- data/lib/ddtrace/contrib/racecar/events/message.rb +2 -2
- data/lib/ddtrace/contrib/racecar/ext.rb +25 -0
- data/lib/ddtrace/contrib/racecar/integration.rb +39 -0
- data/lib/ddtrace/contrib/racecar/patcher.rb +11 -42
- data/lib/ddtrace/contrib/rack/configuration/settings.rb +46 -0
- data/lib/ddtrace/contrib/rack/ext.rb +21 -0
- data/lib/ddtrace/contrib/rack/integration.rb +45 -0
- data/lib/ddtrace/contrib/rack/middlewares.rb +105 -54
- data/lib/ddtrace/contrib/rack/patcher.rb +65 -49
- data/lib/ddtrace/contrib/rack/request_queue.rb +17 -7
- data/lib/ddtrace/contrib/rails/auto_instrument_railtie.rb +10 -0
- data/lib/ddtrace/contrib/rails/configuration/settings.rb +93 -0
- data/lib/ddtrace/contrib/rails/ext.rb +17 -0
- data/lib/ddtrace/contrib/rails/framework.rb +82 -33
- data/lib/ddtrace/contrib/rails/integration.rb +44 -0
- data/lib/ddtrace/contrib/rails/log_injection.rb +81 -0
- data/lib/ddtrace/contrib/rails/middlewares.rb +8 -2
- data/lib/ddtrace/contrib/rails/patcher.rb +88 -34
- data/lib/ddtrace/contrib/rails/railtie.rb +5 -9
- data/lib/ddtrace/contrib/rails/utils.rb +7 -31
- data/lib/ddtrace/contrib/rake/configuration/settings.rb +31 -0
- data/lib/ddtrace/contrib/rake/ext.rb +21 -0
- data/lib/ddtrace/contrib/rake/instrumentation.rb +33 -13
- data/lib/ddtrace/contrib/rake/integration.rb +38 -0
- data/lib/ddtrace/contrib/rake/patcher.rb +10 -33
- data/lib/ddtrace/contrib/redis/configuration/resolver.rb +45 -0
- data/lib/ddtrace/contrib/redis/configuration/settings.rb +35 -0
- data/lib/ddtrace/contrib/redis/ext.rb +22 -0
- data/lib/ddtrace/contrib/redis/integration.rb +42 -0
- data/lib/ddtrace/contrib/redis/patcher.rb +58 -53
- data/lib/ddtrace/contrib/redis/quantize.rb +47 -1
- data/lib/ddtrace/contrib/redis/tags.rb +33 -7
- data/lib/ddtrace/contrib/redis/vendor/LICENSE +20 -0
- data/lib/ddtrace/contrib/redis/vendor/resolver.rb +158 -0
- data/lib/ddtrace/contrib/registerable.rb +33 -0
- data/lib/ddtrace/contrib/registry.rb +42 -0
- data/lib/ddtrace/contrib/resque/configuration/settings.rb +32 -0
- data/lib/ddtrace/contrib/resque/ext.rb +17 -0
- data/lib/ddtrace/contrib/resque/integration.rb +47 -0
- data/lib/ddtrace/contrib/resque/patcher.rb +16 -38
- data/lib/ddtrace/contrib/resque/resque_job.rb +61 -20
- data/lib/ddtrace/contrib/rest_client/configuration/settings.rb +31 -0
- data/lib/ddtrace/contrib/rest_client/ext.rb +17 -0
- data/lib/ddtrace/contrib/rest_client/integration.rb +38 -0
- data/lib/ddtrace/contrib/rest_client/patcher.rb +23 -0
- data/lib/ddtrace/contrib/rest_client/request_patch.rb +91 -0
- data/lib/ddtrace/contrib/rspec/configuration/settings.rb +28 -0
- data/lib/ddtrace/contrib/rspec/example.rb +75 -0
- data/lib/ddtrace/contrib/rspec/ext.rb +16 -0
- data/lib/ddtrace/contrib/rspec/integration.rb +46 -0
- data/lib/ddtrace/contrib/rspec/patcher.rb +23 -0
- data/lib/ddtrace/contrib/sequel/configuration/settings.rb +28 -0
- data/lib/ddtrace/contrib/sequel/database.rb +9 -4
- data/lib/ddtrace/contrib/sequel/dataset.rb +7 -3
- data/lib/ddtrace/contrib/sequel/ext.rb +19 -0
- data/lib/ddtrace/contrib/sequel/integration.rb +38 -0
- data/lib/ddtrace/contrib/sequel/patcher.rb +6 -29
- data/lib/ddtrace/contrib/sequel/utils.rb +60 -14
- data/lib/ddtrace/contrib/shoryuken/configuration/settings.rb +30 -0
- data/lib/ddtrace/contrib/shoryuken/ext.rb +21 -0
- data/lib/ddtrace/contrib/shoryuken/integration.rb +39 -0
- data/lib/ddtrace/contrib/shoryuken/patcher.rb +24 -0
- data/lib/ddtrace/contrib/shoryuken/tracer.rb +51 -0
- data/lib/ddtrace/contrib/sidekiq/client_tracer.rb +43 -0
- data/lib/ddtrace/contrib/sidekiq/configuration/settings.rb +37 -0
- data/lib/ddtrace/contrib/sidekiq/ext.rb +27 -0
- data/lib/ddtrace/contrib/sidekiq/integration.rb +38 -0
- data/lib/ddtrace/contrib/sidekiq/patcher.rb +22 -14
- data/lib/ddtrace/contrib/sidekiq/server_tracer.rb +65 -0
- data/lib/ddtrace/contrib/sidekiq/tracing.rb +44 -0
- data/lib/ddtrace/contrib/sinatra/configuration/settings.rb +39 -0
- data/lib/ddtrace/contrib/sinatra/env.rb +27 -9
- data/lib/ddtrace/contrib/sinatra/ext.rb +27 -0
- data/lib/ddtrace/contrib/sinatra/headers.rb +1 -3
- data/lib/ddtrace/contrib/sinatra/integration.rb +38 -0
- data/lib/ddtrace/contrib/sinatra/patcher.rb +28 -0
- data/lib/ddtrace/contrib/sinatra/tracer.rb +79 -65
- data/lib/ddtrace/contrib/sinatra/tracer_middleware.rb +60 -16
- data/lib/ddtrace/contrib/sneakers/configuration/settings.rb +33 -0
- data/lib/ddtrace/contrib/sneakers/ext.rb +22 -0
- data/lib/ddtrace/contrib/sneakers/integration.rb +41 -0
- data/lib/ddtrace/contrib/sneakers/patcher.rb +24 -0
- data/lib/ddtrace/contrib/sneakers/tracer.rb +53 -0
- data/lib/ddtrace/contrib/status_code_matcher.rb +69 -0
- data/lib/ddtrace/contrib/sucker_punch/configuration/settings.rb +30 -0
- data/lib/ddtrace/contrib/sucker_punch/ext.rb +21 -0
- data/lib/ddtrace/contrib/sucker_punch/instrumentation.rb +29 -5
- data/lib/ddtrace/contrib/sucker_punch/integration.rb +38 -0
- data/lib/ddtrace/contrib/sucker_punch/patcher.rb +21 -33
- data/lib/ddtrace/correlation.rb +39 -0
- data/lib/ddtrace/diagnostics/environment_logger.rb +279 -0
- data/lib/ddtrace/diagnostics/health.rb +33 -0
- data/lib/ddtrace/distributed_tracing/headers/b3.rb +44 -0
- data/lib/ddtrace/distributed_tracing/headers/b3_single.rb +56 -0
- data/lib/ddtrace/distributed_tracing/headers/datadog.rb +42 -0
- data/lib/ddtrace/distributed_tracing/headers/headers.rb +71 -0
- data/lib/ddtrace/distributed_tracing/headers/helpers.rb +43 -0
- data/lib/ddtrace/encoding.rb +36 -32
- data/lib/ddtrace/environment.rb +41 -0
- data/lib/ddtrace/event.rb +52 -0
- data/lib/ddtrace/ext/analytics.rb +12 -0
- data/lib/ddtrace/ext/app_types.rb +1 -0
- data/lib/ddtrace/ext/ci.rb +297 -0
- data/lib/ddtrace/ext/correlation.rb +11 -0
- data/lib/ddtrace/ext/diagnostics.rb +36 -0
- data/lib/ddtrace/ext/distributed.rb +22 -0
- data/lib/ddtrace/ext/environment.rb +16 -0
- data/lib/ddtrace/ext/forced_tracing.rb +25 -0
- data/lib/ddtrace/ext/git.rb +11 -0
- data/lib/ddtrace/ext/http.rb +4 -2
- data/lib/ddtrace/ext/integration.rb +8 -0
- data/lib/ddtrace/ext/manual_tracing.rb +9 -0
- data/lib/ddtrace/ext/metrics.rb +15 -0
- data/lib/ddtrace/ext/net.rb +2 -0
- data/lib/ddtrace/ext/runtime.rb +30 -0
- data/lib/ddtrace/ext/sampling.rb +16 -0
- data/lib/ddtrace/ext/test.rb +24 -0
- data/lib/ddtrace/ext/transport.rb +18 -0
- data/lib/ddtrace/forced_tracing.rb +38 -0
- data/lib/ddtrace/logger.rb +5 -4
- data/lib/ddtrace/metrics.rb +226 -0
- data/lib/ddtrace/opentelemetry/extensions.rb +13 -0
- data/lib/ddtrace/opentelemetry/span.rb +33 -0
- data/lib/ddtrace/opentracer.rb +40 -0
- data/lib/ddtrace/opentracer/binary_propagator.rb +24 -0
- data/lib/ddtrace/opentracer/carrier.rb +6 -0
- data/lib/ddtrace/opentracer/distributed_headers.rb +55 -0
- data/lib/ddtrace/opentracer/global_tracer.rb +15 -0
- data/lib/ddtrace/opentracer/propagator.rb +22 -0
- data/lib/ddtrace/opentracer/rack_propagator.rb +60 -0
- data/lib/ddtrace/opentracer/scope.rb +15 -0
- data/lib/ddtrace/opentracer/scope_manager.rb +6 -0
- data/lib/ddtrace/opentracer/span.rb +94 -0
- data/lib/ddtrace/opentracer/span_context.rb +14 -0
- data/lib/ddtrace/opentracer/span_context_factory.rb +23 -0
- data/lib/ddtrace/opentracer/text_map_propagator.rb +75 -0
- data/lib/ddtrace/opentracer/thread_local_scope.rb +31 -0
- data/lib/ddtrace/opentracer/thread_local_scope_manager.rb +40 -0
- data/lib/ddtrace/opentracer/tracer.rb +208 -0
- data/lib/ddtrace/patcher.rb +33 -5
- data/lib/ddtrace/pin.rb +35 -20
- data/lib/ddtrace/pipeline.rb +1 -1
- data/lib/ddtrace/pipeline/span_filter.rb +15 -15
- data/lib/ddtrace/propagation/grpc_propagator.rb +26 -6
- data/lib/ddtrace/propagation/http_propagator.rb +72 -10
- data/lib/ddtrace/quantization/http.rb +1 -0
- data/lib/ddtrace/runtime/cgroup.rb +44 -0
- data/lib/ddtrace/runtime/class_count.rb +17 -0
- data/lib/ddtrace/runtime/container.rb +71 -0
- data/lib/ddtrace/runtime/gc.rb +16 -0
- data/lib/ddtrace/runtime/identity.rb +48 -0
- data/lib/ddtrace/runtime/metrics.rb +114 -0
- data/lib/ddtrace/runtime/object_space.rb +19 -0
- data/lib/ddtrace/runtime/socket.rb +14 -0
- data/lib/ddtrace/runtime/thread_count.rb +16 -0
- data/lib/ddtrace/sampler.rb +218 -37
- data/lib/ddtrace/sampling.rb +2 -0
- data/lib/ddtrace/sampling/matcher.rb +57 -0
- data/lib/ddtrace/sampling/rate_limiter.rb +176 -0
- data/lib/ddtrace/sampling/rule.rb +61 -0
- data/lib/ddtrace/sampling/rule_sampler.rb +126 -0
- data/lib/ddtrace/span.rb +244 -34
- data/lib/ddtrace/sync_writer.rb +47 -16
- data/lib/ddtrace/tracer.rb +215 -117
- data/lib/ddtrace/transport/http.rb +113 -0
- data/lib/ddtrace/transport/http/adapters/net.rb +145 -0
- data/lib/ddtrace/transport/http/adapters/registry.rb +25 -0
- data/lib/ddtrace/transport/http/adapters/test.rb +83 -0
- data/lib/ddtrace/transport/http/adapters/unix_socket.rb +66 -0
- data/lib/ddtrace/transport/http/api.rb +46 -0
- data/lib/ddtrace/transport/http/api/endpoint.rb +27 -0
- data/lib/ddtrace/transport/http/api/fallbacks.rb +22 -0
- data/lib/ddtrace/transport/http/api/instance.rb +33 -0
- data/lib/ddtrace/transport/http/api/map.rb +14 -0
- data/lib/ddtrace/transport/http/api/spec.rb +15 -0
- data/lib/ddtrace/transport/http/builder.rb +169 -0
- data/lib/ddtrace/transport/http/client.rb +50 -0
- data/lib/ddtrace/transport/http/env.rb +56 -0
- data/lib/ddtrace/transport/http/response.rb +26 -0
- data/lib/ddtrace/transport/http/statistics.rb +43 -0
- data/lib/ddtrace/transport/http/traces.rb +142 -0
- data/lib/ddtrace/transport/io.rb +26 -0
- data/lib/ddtrace/transport/io/client.rb +76 -0
- data/lib/ddtrace/transport/io/response.rb +23 -0
- data/lib/ddtrace/transport/io/traces.rb +97 -0
- data/lib/ddtrace/transport/parcel.rb +13 -0
- data/lib/ddtrace/transport/request.rb +13 -0
- data/lib/ddtrace/transport/response.rb +60 -0
- data/lib/ddtrace/transport/statistics.rb +72 -0
- data/lib/ddtrace/transport/traces.rb +205 -0
- data/lib/ddtrace/utils.rb +17 -14
- data/lib/ddtrace/utils/compression.rb +27 -0
- data/lib/ddtrace/utils/database.rb +7 -3
- data/lib/ddtrace/utils/forking.rb +52 -0
- data/lib/ddtrace/utils/object_set.rb +41 -0
- data/lib/ddtrace/utils/only_once.rb +40 -0
- data/lib/ddtrace/utils/sequence.rb +17 -0
- data/lib/ddtrace/utils/string_table.rb +45 -0
- data/lib/ddtrace/utils/time.rb +45 -0
- data/lib/ddtrace/vendor/active_record/MIT-LICENSE +20 -0
- data/lib/ddtrace/vendor/active_record/connection_specification.rb +301 -0
- data/lib/ddtrace/vendor/multipart-post/LICENSE +11 -0
- data/lib/ddtrace/vendor/multipart-post/multipart.rb +12 -0
- data/lib/ddtrace/vendor/multipart-post/multipart/post.rb +8 -0
- data/lib/ddtrace/vendor/multipart-post/multipart/post/composite_read_io.rb +116 -0
- data/lib/ddtrace/vendor/multipart-post/multipart/post/multipartable.rb +57 -0
- data/lib/ddtrace/vendor/multipart-post/multipart/post/parts.rb +135 -0
- data/lib/ddtrace/vendor/multipart-post/multipart/post/version.rb +9 -0
- data/lib/ddtrace/vendor/multipart-post/net/http/post/multipart.rb +32 -0
- data/lib/ddtrace/version.rb +3 -1
- data/lib/ddtrace/worker.rb +20 -0
- data/lib/ddtrace/workers.rb +39 -40
- data/lib/ddtrace/workers/async.rb +173 -0
- data/lib/ddtrace/workers/loop.rb +119 -0
- data/lib/ddtrace/workers/polling.rb +49 -0
- data/lib/ddtrace/workers/queue.rb +40 -0
- data/lib/ddtrace/workers/runtime_metrics.rb +51 -0
- data/lib/ddtrace/workers/trace_writer.rb +202 -0
- data/lib/ddtrace/writer.rb +121 -57
- data/tasks/release_gem.rake +28 -0
- metadata +501 -211
- data/lib/ddtrace/configurable.rb +0 -83
- data/lib/ddtrace/configuration/proxy.rb +0 -25
- data/lib/ddtrace/contrib/base.rb +0 -15
- data/lib/ddtrace/contrib/mysql2/client.rb +0 -60
- data/lib/ddtrace/contrib/rails/action_controller.rb +0 -91
- data/lib/ddtrace/contrib/rails/action_controller_patch.rb +0 -77
- data/lib/ddtrace/contrib/rails/action_view.rb +0 -19
- data/lib/ddtrace/contrib/rails/active_support.rb +0 -65
- data/lib/ddtrace/contrib/rails/core_extensions.rb +0 -356
- data/lib/ddtrace/contrib/sidekiq/tracer.rb +0 -72
- data/lib/ddtrace/ext/cache.rb +0 -8
- data/lib/ddtrace/ext/grpc.rb +0 -7
- data/lib/ddtrace/ext/mongo.rb +0 -12
- data/lib/ddtrace/ext/redis.rb +0 -17
- data/lib/ddtrace/monkey.rb +0 -65
- data/lib/ddtrace/propagation/distributed_headers.rb +0 -48
- data/lib/ddtrace/provider.rb +0 -21
- data/lib/ddtrace/registry.rb +0 -42
- data/lib/ddtrace/registry/registerable.rb +0 -20
- data/lib/ddtrace/transport.rb +0 -212
@@ -0,0 +1,249 @@
|
|
1
|
+
# Developing
|
2
|
+
|
3
|
+
This guide covers some of the common how-tos and technical reference material for developing changes within the trace library.
|
4
|
+
|
5
|
+
## Table of Contents
|
6
|
+
|
7
|
+
- [Setting up](#setting-up)
|
8
|
+
- [Testing](#testing)
|
9
|
+
- [Writing tests](#writing-tests)
|
10
|
+
- [Running tests](#running-tests)
|
11
|
+
- [Checking code quality](#checking-code-quality)
|
12
|
+
- [Appendix](#appendix)
|
13
|
+
- [Writing new integrations](#writing-new-integrations)
|
14
|
+
- [Custom transport adapters](#custom-transport-adapters)
|
15
|
+
|
16
|
+
## Setting up
|
17
|
+
|
18
|
+
*NOTE: To test locally, you must have `Docker` and `Docker Compose` installed. See the [Docker documentation](https://docs.docker.com/compose/install/) for details.*
|
19
|
+
|
20
|
+
The trace library uses Docker Compose to create a Ruby environment to develop and test within, as well as containers for any dependencies that might be necessary for certain kinds of tests.
|
21
|
+
|
22
|
+
To start a development environment, choose a target Ruby version then run the following:
|
23
|
+
|
24
|
+
```
|
25
|
+
# In the root directory of the project...
|
26
|
+
cd ~/dd-trace-rb
|
27
|
+
|
28
|
+
# Create and start a Ruby 2.3 test environment with its dependencies
|
29
|
+
docker-compose run --rm tracer-2.3 /bin/bash
|
30
|
+
|
31
|
+
# Then inside the container (e.g. `root@2a73c6d8673e:/app`)...
|
32
|
+
# Install the library dependencies
|
33
|
+
bundle install
|
34
|
+
|
35
|
+
# Install build targets
|
36
|
+
appraisal install
|
37
|
+
```
|
38
|
+
|
39
|
+
Then within this container you can [run tests](#running-tests), or [run code quality checks](#checking-code-quality).
|
40
|
+
|
41
|
+
## Testing
|
42
|
+
|
43
|
+
The test suite uses both [Minitest](https://github.com/seattlerb/minitest) and [RSpec](https://rspec.info/) tests to verify the correctness of both the core trace library and its integrations.
|
44
|
+
|
45
|
+
Minitest is deprecated in favor of RSpec; all new tests should be written in RSpec, and only existing minitests should be updated.
|
46
|
+
|
47
|
+
### Writing tests
|
48
|
+
|
49
|
+
New tests should be written as RSpec tests in the `spec/ddtrace` folder. Test files should generally mirror the structure of `lib`.
|
50
|
+
|
51
|
+
All changes should be covered by a corresponding RSpec tests. Unit tests are preferred, and integration tests are accepted where appropriate (e.g. acceptance tests, verifying compatibility with datastores, etc) but should be kept to a minimum.
|
52
|
+
|
53
|
+
**Considerations for CI**
|
54
|
+
|
55
|
+
All tests should run in CI. When adding new `spec.rb` files, you may need to add a test task to ensure your test file is run in CI.
|
56
|
+
|
57
|
+
- Ensure that there is a corresponding Rake task defined in `Rakefile` under the the `spec` namespace, whose pattern matches your test file.
|
58
|
+
- Verify the Rake task is configured to run for the appropriate Ruby runtimes in the `ci` Rake task.
|
59
|
+
|
60
|
+
### Running tests
|
61
|
+
|
62
|
+
Simplest way to run tests is to run `bundle exec rake ci`, which will run the entire test suite, just as CI does.
|
63
|
+
|
64
|
+
**For the core library**
|
65
|
+
|
66
|
+
Run the tests for the core library with:
|
67
|
+
|
68
|
+
```
|
69
|
+
# Run Minitest
|
70
|
+
$ bundle exec rake test:main
|
71
|
+
# Run RSpec
|
72
|
+
$ bundle exec rake spec:main
|
73
|
+
```
|
74
|
+
|
75
|
+
**For integrations**
|
76
|
+
|
77
|
+
Integrations which interact with dependencies not listed in the `ddtrace` gemspec will need to load these dependencies to run their tests.
|
78
|
+
|
79
|
+
To do so, load the dependencies using [Appraisal](https://github.com/thoughtbot/appraisal). You can see a list of available appraisals with `bundle exec appraisal list`, or examine the `Appraisals` file.
|
80
|
+
|
81
|
+
Then to run tests, prefix the test commain with the appraisal. For example:
|
82
|
+
|
83
|
+
```
|
84
|
+
# Runs tests for Rails 3.2 + Postgres
|
85
|
+
$ bundle exec appraisal rails32-postgres spec:rails
|
86
|
+
# Runs tests for Redis
|
87
|
+
$ bundle exec appraisal contrib rake spec:redis
|
88
|
+
```
|
89
|
+
|
90
|
+
**Passing arguments to tests**
|
91
|
+
|
92
|
+
When running RSpec tests, you may pass additional args as parameters to the Rake task. For example:
|
93
|
+
|
94
|
+
```
|
95
|
+
# Runs Redis tests with seed 1234
|
96
|
+
$ bundle exec appraisal contrib rake spec:redis'[--seed,1234]'
|
97
|
+
```
|
98
|
+
|
99
|
+
This can be useful for replicating conditions from CI or isolating certain tests.
|
100
|
+
|
101
|
+
**Checking test coverage**
|
102
|
+
|
103
|
+
You can check test code coverage by creating a report _after_ running a test suite:
|
104
|
+
```
|
105
|
+
# Run the desired test suite
|
106
|
+
$ bundle exec appraisal contrib rake spec:redis
|
107
|
+
# Generate report for the suite executed
|
108
|
+
$ bundle exec rake coverage:report
|
109
|
+
```
|
110
|
+
|
111
|
+
A webpage will be generated at `coverage/report/index.html` with the resulting report.
|
112
|
+
|
113
|
+
Because you are likely not running all tests locally, your report will contain partial coverage results.
|
114
|
+
You *must* check the CI step `coverage` for the complete test coverage report, ensuring coverage is not
|
115
|
+
decreased.
|
116
|
+
|
117
|
+
**Ensuring tests don't leak resources**
|
118
|
+
|
119
|
+
Tests execution can create resources that are hard to track: threads, sockets, files, etc. Because these resources can come
|
120
|
+
from the both the test setup as well as the code under test, making sure all resources are properly disposed is important
|
121
|
+
to prevent the application from inadvertently creating cumulative resources during its execution.
|
122
|
+
|
123
|
+
When running tests that utilize threads, you might see an error message similar to this one:
|
124
|
+
|
125
|
+
```
|
126
|
+
Test leaked 1 thread: "Datadog::Workers::AsyncTransport integration tests"
|
127
|
+
Ensure all threads are terminated when test finishes:
|
128
|
+
1: #<Thread:0x00007fcbc99863d0 /Users/marco.costa/work/dd-trace-rb/spec/spec_helper.rb:145 sleep> (Thread)
|
129
|
+
Thread Creation Site:
|
130
|
+
./dd-trace-rb/spec/ddtrace/workers_integration_spec.rb:245:in 'new'
|
131
|
+
./dd-trace-rb/spec/ddtrace/workers_integration_spec.rb:245:in 'block (4 levels) in <top (required)>'
|
132
|
+
Thread Backtrace:
|
133
|
+
./dd-trace-rb/spec/ddtrace/workers_integration_spec.rb:262:in 'sleep'
|
134
|
+
.dd-trace-rb/spec/ddtrace/workers_integration_spec.rb:262:in 'block (5 levels) in <top (required)>'
|
135
|
+
./dd-trace-rb/spec/spec_helper.rb:147:in 'block in initialize'
|
136
|
+
```
|
137
|
+
|
138
|
+
This means that this test did not finish all threads by the time the test had finished. In this case, the thread
|
139
|
+
creation can be traced to `workers_integration_spec.rb:245:in 'new'`. The thread itself is sleeping at `workers_integration_spec.rb:262:in 'sleep'`.
|
140
|
+
|
141
|
+
The actionable in this case would be to ensure that the thread created in `workers_integration_spec.rb:245` is properly terminated by invoking `Thread#join` during the test tear down, which will wait for the thread to finish before returning.
|
142
|
+
|
143
|
+
Depending on the situation, the thread in question might need to be forced to terminate. It's recommended to have a mechanism in place to terminate it (a shared variable that changes value when the thread should exit), but as a last resort, `Thread#terminate` forces the thread to finish. Keep in mind that regardless of the termination method, `Thread#join` must be called to ensure that the thread has completely finished its shutdown process.
|
144
|
+
|
145
|
+
### Checking code quality
|
146
|
+
|
147
|
+
**Linting**
|
148
|
+
|
149
|
+
The trace library uses Rubocop to enforce [code style](https://github.com/bbatsov/ruby-style-guide) and quality. To check, run:
|
150
|
+
|
151
|
+
```
|
152
|
+
$ bundle exec rake rubocop
|
153
|
+
```
|
154
|
+
|
155
|
+
### Running benchmarks
|
156
|
+
|
157
|
+
If your changes can have a measurable performance impact, we recommend running our benchmark suite:
|
158
|
+
|
159
|
+
```
|
160
|
+
$ bundle exec rake spec:benchmark
|
161
|
+
```
|
162
|
+
|
163
|
+
Results are printed to STDOUT as well as written to the `./tmp/benchmark/` directory.
|
164
|
+
|
165
|
+
## Appendix
|
166
|
+
|
167
|
+
### Writing new integrations
|
168
|
+
|
169
|
+
Integrations are extensions to the trace library that add support for external dependencies (gems); they typically add auto-instrumentation to popular gems and frameworks. You will find many of our integrations in the `contrib` folder.
|
170
|
+
|
171
|
+
Some general guidelines for adding new integrations:
|
172
|
+
|
173
|
+
- An integration can either be added directly to `dd-trace-rb`, or developed as its own gem that depends on `ddtrace`.
|
174
|
+
- Integrations should implement the configuration API for easy, consistent implementation. (See existing integrations as examples of this.)
|
175
|
+
- All new integrations require documentation, unit/integration tests written in RSpec, and passing CI builds.
|
176
|
+
- It's highly encouraged to share screenshots or other demos of how the new integration looks and works.
|
177
|
+
|
178
|
+
To get started quickly, it's perfectly fine to copy-paste an existing integration to use as a template, then modify it to match your needs. This is usually the fastest, easiest way to bootstrap a new integration and makes the time-to-first-trace often very quick, usually less than an hour if it's a simple implementation.
|
179
|
+
|
180
|
+
Once you have it working in your application, you can [add unit tests](#writing-tests), [run them locally](#running-tests), and [check for code quality](#checking-code-quality) using Docker Compose.
|
181
|
+
|
182
|
+
Then [open a pull request](../CONTRIBUTING.md#have-a-patch) and be sure to add the following to the description:
|
183
|
+
|
184
|
+
- [Documentation](./GettingStarted.md) for the integration, including versions supported.
|
185
|
+
- Links to the repository/website of the library being integrated
|
186
|
+
- Screenshots showing a sample trace
|
187
|
+
- Any additional code snippets, sample apps, benchmarks, or other resources that demonstrate its implementation are a huge plus!
|
188
|
+
|
189
|
+
### Custom transport adapters
|
190
|
+
|
191
|
+
The tracer can be configured with transports that customize how data is sent and where it is sent to. This is done through the use of adapters: classes that receive generic requests, process them, and return appropriate responses.
|
192
|
+
|
193
|
+
#### Developing HTTP transport adapters
|
194
|
+
|
195
|
+
To create a custom HTTP adapter, define a class that responds to `call(env)` which returns a kind of `Datadog::Transport::Response`:
|
196
|
+
|
197
|
+
```ruby
|
198
|
+
require 'ddtrace/transport/response'
|
199
|
+
|
200
|
+
class CustomAdapter
|
201
|
+
# Sends HTTP request
|
202
|
+
# env: Datadog::Transport::HTTP::Env
|
203
|
+
def call(env)
|
204
|
+
# Add custom code here to send data.
|
205
|
+
# Then return a Response object.
|
206
|
+
Response.new
|
207
|
+
end
|
208
|
+
|
209
|
+
class Response
|
210
|
+
include Datadog::Transport::Response
|
211
|
+
|
212
|
+
# Implement the following methods as appropriate
|
213
|
+
# for your adapter.
|
214
|
+
|
215
|
+
# Return a String
|
216
|
+
def payload; end
|
217
|
+
|
218
|
+
# Return true/false
|
219
|
+
# Return nil if it does not apply
|
220
|
+
def ok?; end
|
221
|
+
def unsupported?; end
|
222
|
+
def not_found?; end
|
223
|
+
def client_error?; end
|
224
|
+
def server_error?; end
|
225
|
+
def internal_error?; end
|
226
|
+
end
|
227
|
+
end
|
228
|
+
```
|
229
|
+
|
230
|
+
Optionally, you can register the adapter as a well-known type:
|
231
|
+
|
232
|
+
```ruby
|
233
|
+
Datadog::Transport::HTTP::Builder::REGISTRY.set(CustomAdapter, :custom)
|
234
|
+
```
|
235
|
+
|
236
|
+
Then pass an adapter instance to the tracer configuration:
|
237
|
+
|
238
|
+
```ruby
|
239
|
+
Datadog.configure do |c|
|
240
|
+
c.tracer.transport_options = proc { |t|
|
241
|
+
# By name
|
242
|
+
t.adapter :custom
|
243
|
+
|
244
|
+
# By instance
|
245
|
+
custom_adapter = CustomAdapter.new
|
246
|
+
t.adapter custom_adapter
|
247
|
+
}
|
248
|
+
end
|
249
|
+
```
|
data/docs/GettingStarted.md
CHANGED
@@ -1,19 +1,21 @@
|
|
1
|
-
# Datadog Trace Client
|
1
|
+
# Datadog Ruby Trace Client
|
2
2
|
|
3
|
-
|
4
|
-
databases and microservices so that developers have
|
3
|
+
`ddtrace` is Datadog’s tracing client for Ruby. It is used to trace requests as they flow across web servers,
|
4
|
+
databases and microservices so that developers have high visibility into bottlenecks and troublesome requests.
|
5
5
|
|
6
6
|
## Getting started
|
7
7
|
|
8
|
-
For
|
8
|
+
For the general APM documentation, see our [setup documentation][setup docs].
|
9
9
|
|
10
|
-
For
|
10
|
+
For more information about what APM looks like once your application is sending information to Datadog, take a look at [Visualizing your APM data][visualization docs].
|
11
11
|
|
12
|
-
|
12
|
+
To contribute, check out the [contribution guidelines][contribution docs] and [development guide][development docs].
|
13
13
|
|
14
|
-
[setup docs]: https://docs.datadoghq.com/tracing/
|
14
|
+
[setup docs]: https://docs.datadoghq.com/tracing/
|
15
15
|
[development docs]: https://github.com/DataDog/dd-trace-rb/blob/master/README.md#development
|
16
16
|
[visualization docs]: https://docs.datadoghq.com/tracing/visualization/
|
17
|
+
[contribution docs]: https://github.com/DataDog/dd-trace-rb/blob/master/CONTRIBUTING.md
|
18
|
+
[development docs]: https://github.com/DataDog/dd-trace-rb/blob/master/docs/DevelopmentGuide.md
|
17
19
|
|
18
20
|
## Table of Contents
|
19
21
|
|
@@ -21,28 +23,49 @@ For descriptions of terminology used in APM, take a look at the [official docume
|
|
21
23
|
- [Installation](#installation)
|
22
24
|
- [Quickstart for Rails applications](#quickstart-for-rails-applications)
|
23
25
|
- [Quickstart for Ruby applications](#quickstart-for-ruby-applications)
|
26
|
+
- [Quickstart for OpenTracing](#quickstart-for-opentracing)
|
24
27
|
- [Manual instrumentation](#manual-instrumentation)
|
25
28
|
- [Integration instrumentation](#integration-instrumentation)
|
29
|
+
- [Action Cable](#action-cable)
|
30
|
+
- [Action View](#action-view)
|
31
|
+
- [Active Model Serializers](#active-model-serializers)
|
32
|
+
- [Action Pack](#action-pack)
|
26
33
|
- [Active Record](#active-record)
|
34
|
+
- [Active Support](#active-support)
|
27
35
|
- [AWS](#aws)
|
36
|
+
- [Concurrent Ruby](#concurrent-ruby)
|
37
|
+
- [Cucumber](#cucumber)
|
28
38
|
- [Dalli](#dalli)
|
29
|
-
- [
|
39
|
+
- [DelayedJob](#delayedjob)
|
40
|
+
- [Elasticsearch](#elasticsearch)
|
41
|
+
- [Ethon & Typhoeus](#ethon)
|
30
42
|
- [Excon](#excon)
|
31
43
|
- [Faraday](#faraday)
|
32
|
-
- [gRPC](#grpc)
|
33
44
|
- [Grape](#grape)
|
34
45
|
- [GraphQL](#graphql)
|
46
|
+
- [gRPC](#grpc)
|
47
|
+
- [http.rb](#http-rb)
|
48
|
+
- [httpclient](#httpclient)
|
49
|
+
- [httpx](#httpx)
|
35
50
|
- [MongoDB](#mongodb)
|
36
|
-
- [
|
51
|
+
- [MySQL2](#mysql2)
|
52
|
+
- [Net/HTTP](#net-http)
|
53
|
+
- [Presto](#presto)
|
54
|
+
- [Qless](#qless)
|
55
|
+
- [Que](#que)
|
37
56
|
- [Racecar](#racecar)
|
38
57
|
- [Rack](#rack)
|
39
58
|
- [Rails](#rails)
|
40
59
|
- [Rake](#rake)
|
41
60
|
- [Redis](#redis)
|
61
|
+
- [Rest Client](#rest-client)
|
42
62
|
- [Resque](#resque)
|
63
|
+
- [RSpec](#rspec)
|
64
|
+
- [Shoryuken](#shoryuken)
|
43
65
|
- [Sequel](#sequel)
|
44
66
|
- [Sidekiq](#sidekiq)
|
45
67
|
- [Sinatra](#sinatra)
|
68
|
+
- [Sneakers](#sneakers)
|
46
69
|
- [Sucker Punch](#sucker-punch)
|
47
70
|
- [Advanced configuration](#advanced-configuration)
|
48
71
|
- [Tracer settings](#tracer-settings)
|
@@ -55,25 +78,30 @@ For descriptions of terminology used in APM, take a look at the [official docume
|
|
55
78
|
- [Processing pipeline](#processing-pipeline)
|
56
79
|
- [Filtering](#filtering)
|
57
80
|
- [Processing](#processing)
|
81
|
+
- [Trace correlation](#trace-correlation)
|
82
|
+
- [Configuring the transport layer](#configuring-the-transport-layer)
|
83
|
+
- [Metrics](#metrics)
|
84
|
+
- [For application runtime](#for-application-runtime)
|
85
|
+
- [OpenTracing](#opentracing)
|
58
86
|
|
59
87
|
## Compatibility
|
60
88
|
|
61
89
|
**Supported Ruby interpreters**:
|
62
90
|
|
63
|
-
| Type | Documentation | Version | Support type |
|
64
|
-
| ----- | -------------------------- | ----- |
|
65
|
-
| MRI | https://www.ruby-lang.org/ |
|
66
|
-
| | |
|
67
|
-
| | | 2.
|
68
|
-
| | | 2.
|
69
|
-
| | | 2.
|
70
|
-
| | | 2.3 | Full
|
71
|
-
| | | 2.
|
72
|
-
|
|
73
|
-
|
74
|
-
|
75
|
-
|
76
|
-
|
91
|
+
| Type | Documentation | Version | Support type | Gem version support |
|
92
|
+
| ----- | -------------------------- | ----- | ------------------------------------ | ------------------- |
|
93
|
+
| MRI | https://www.ruby-lang.org/ | 3.0 | Full | Latest |
|
94
|
+
| | | 2.7 | Full | Latest |
|
95
|
+
| | | 2.6 | Full | Latest |
|
96
|
+
| | | 2.5 | Full | Latest |
|
97
|
+
| | | 2.4 | Full | Latest |
|
98
|
+
| | | 2.3 | Full | Latest |
|
99
|
+
| | | 2.2 | Full | Latest |
|
100
|
+
| | | 2.1 | Full | Latest |
|
101
|
+
| | | 2.0 | Full | Latest |
|
102
|
+
| | | 1.9.3 | EOL since August 6th, 2020 | < 0.27.0 |
|
103
|
+
| | | 1.9.1 | EOL since August 6th, 2020 | < 0.27.0 |
|
104
|
+
| JRuby | https://www.jruby.org | 9.2 | Full | Latest |
|
77
105
|
|
78
106
|
**Supported web servers**:
|
79
107
|
|
@@ -83,20 +111,58 @@ For descriptions of terminology used in APM, take a look at the [official docume
|
|
83
111
|
| Unicorn | https://bogomips.org/unicorn/ | 4.8+ / 5.1+ | Full |
|
84
112
|
| Passenger | https://www.phusionpassenger.com/ | 5.0+ | Full |
|
85
113
|
|
114
|
+
**Supported tracing frameworks**:
|
115
|
+
|
116
|
+
| Type | Documentation | Version | Gem version support |
|
117
|
+
| ----------- | ----------------------------------------------- | --------------------- | ------------------- |
|
118
|
+
| OpenTracing | https://github.com/opentracing/opentracing-ruby | 0.4.1+ (w/ Ruby 2.1+) | >= 0.16.0 |
|
119
|
+
|
120
|
+
*Full* support indicates all tracer features are available.
|
121
|
+
|
122
|
+
*Deprecated* indicates support will transition to *Maintenance* in a future release.
|
123
|
+
|
124
|
+
*Maintenance* indicates only critical bugfixes are backported until EOL.
|
125
|
+
|
126
|
+
*EOL* indicates support is no longer provided.
|
127
|
+
|
86
128
|
## Installation
|
87
129
|
|
88
130
|
The following steps will help you quickly start tracing your Ruby application.
|
89
131
|
|
90
|
-
###
|
132
|
+
### Configure the Datadog Agent for APM
|
133
|
+
|
134
|
+
Before downloading tracing on your application, install the Datadog Agent. The Ruby APM tracer sends trace data through the Datadog Agent.
|
91
135
|
|
92
|
-
|
136
|
+
Install and configure the Datadog Agent to receive traces from your now instrumented application. By default the Datadog Agent is enabled in your `datadog.yaml` file under `apm_enabled: true` and listens for trace traffic at `localhost:8126`. For containerized environments, follow the steps below to enable trace collection within the Datadog Agent.
|
137
|
+
|
138
|
+
#### Containers
|
139
|
+
|
140
|
+
1. Set `apm_non_local_traffic: true` in your main [`datadog.yaml` configuration file](https://docs.datadoghq.com/agent/guide/agent-configuration-files/#agent-main-configuration-file).
|
141
|
+
|
142
|
+
2. See the specific setup instructions for [Docker](https://docs.datadoghq.com/agent/docker/apm/?tab=ruby), [Kubernetes](https://docs.datadoghq.com/agent/kubernetes/apm/?tab=helm), [Amazon ECS](https://docs.datadoghq.com/agent/amazon_ecs/apm/?tab=ruby) or [Fargate](https://docs.datadoghq.com/integrations/ecs_fargate/#trace-collection) to ensure that the Agent is configured to receive traces in a containerized environment:
|
143
|
+
|
144
|
+
3. After having instrumented your application, the tracing client sends traces to `localhost:8126` by default. If this is not the correct host and port change it by setting the env variables `DD_AGENT_HOST` and `DD_TRACE_AGENT_PORT`.
|
93
145
|
|
94
|
-
[Install and configure the Datadog Agent](https://docs.datadoghq.com/tracing/setup), see additional documentation for [tracing Docker applications](https://docs.datadoghq.com/tracing/setup/docker/).
|
95
146
|
|
96
147
|
### Quickstart for Rails applications
|
97
148
|
|
149
|
+
#### Automatic instrumentation
|
150
|
+
|
151
|
+
1. Add the `ddtrace` gem to your Gemfile:
|
152
|
+
|
153
|
+
```ruby
|
154
|
+
source 'https://rubygems.org'
|
155
|
+
gem 'ddtrace', require: 'ddtrace/auto_instrument'
|
156
|
+
```
|
157
|
+
|
158
|
+
2. Install the gem with `bundle install`
|
159
|
+
|
160
|
+
3. You can configure, override, or disable any specific integration settings by also adding a [Rails Manual Configuration](#rails-manual-configuration) file.
|
161
|
+
|
162
|
+
#### Manual instrumentation
|
163
|
+
|
98
164
|
1. Add the `ddtrace` gem to your Gemfile:
|
99
|
-
|
165
|
+
|
100
166
|
```ruby
|
101
167
|
source 'https://rubygems.org'
|
102
168
|
gem 'ddtrace'
|
@@ -116,6 +182,25 @@ The Ruby APM tracer sends trace data through the Datadog Agent.
|
|
116
182
|
|
117
183
|
### Quickstart for Ruby applications
|
118
184
|
|
185
|
+
#### Automatic instrumentation
|
186
|
+
|
187
|
+
1. Install the gem with `gem install ddtrace`
|
188
|
+
2. Requiring any [supported libraries or frameworks](#integration-instrumentation) that should be instrumented.
|
189
|
+
3. Add `require 'ddtrace/auto_instrument'` to your application. _Note:_ This must be done _after_ requiring any supported libraries or frameworks.
|
190
|
+
|
191
|
+
```ruby
|
192
|
+
# Example frameworks and libraries
|
193
|
+
require 'sinatra'
|
194
|
+
require 'faraday'
|
195
|
+
require 'redis'
|
196
|
+
|
197
|
+
require 'ddtrace/auto_instrument'
|
198
|
+
```
|
199
|
+
|
200
|
+
You can configure, override, or disable any specific integration settings by also adding a [Ruby Manual Configuration Block](#ruby-manual-configuration).
|
201
|
+
|
202
|
+
#### Manual instrumentation
|
203
|
+
|
119
204
|
1. Install the gem with `gem install ddtrace`
|
120
205
|
2. Add a configuration block to your Ruby application:
|
121
206
|
|
@@ -129,8 +214,38 @@ The Ruby APM tracer sends trace data through the Datadog Agent.
|
|
129
214
|
```
|
130
215
|
|
131
216
|
3. Add or activate instrumentation by doing either of the following:
|
132
|
-
|
133
|
-
|
217
|
+
- Activate integration instrumentation (see [Integration instrumentation](#integration-instrumentation))
|
218
|
+
- Add manual instrumentation around your code (see [Manual instrumentation](#manual-instrumentation))
|
219
|
+
|
220
|
+
### Quickstart for OpenTracing
|
221
|
+
|
222
|
+
1. Install the gem with `gem install ddtrace`
|
223
|
+
2. To your OpenTracing configuration file, add the following:
|
224
|
+
|
225
|
+
```ruby
|
226
|
+
require 'opentracing'
|
227
|
+
require 'ddtrace'
|
228
|
+
require 'ddtrace/opentracer'
|
229
|
+
|
230
|
+
# Activate the Datadog tracer for OpenTracing
|
231
|
+
OpenTracing.global_tracer = Datadog::OpenTracer::Tracer.new
|
232
|
+
```
|
233
|
+
|
234
|
+
3. (Optional) Add a configuration block to your Ruby application to configure Datadog with:
|
235
|
+
|
236
|
+
```ruby
|
237
|
+
Datadog.configure do |c|
|
238
|
+
# Configure the Datadog tracer here.
|
239
|
+
# Activate integrations, change tracer settings, etc...
|
240
|
+
# By default without additional configuration,
|
241
|
+
# no additional integrations will be traced, only
|
242
|
+
# what you have instrumented with OpenTracing.
|
243
|
+
end
|
244
|
+
```
|
245
|
+
|
246
|
+
4. (Optional) Add or activate additional instrumentation by doing either of the following:
|
247
|
+
- Activate Datadog integration instrumentation (see [Integration instrumentation](#integration-instrumentation))
|
248
|
+
- Add Datadog manual instrumentation around your code (see [Manual instrumentation](#manual-instrumentation))
|
134
249
|
|
135
250
|
### Final steps for installation
|
136
251
|
|
@@ -138,7 +253,7 @@ After setting up, your services will appear on the [APM services page](https://a
|
|
138
253
|
|
139
254
|
## Manual Instrumentation
|
140
255
|
|
141
|
-
If you aren't using a supported framework instrumentation, you may want to
|
256
|
+
If you aren't using a supported framework instrumentation, you may want to manually instrument your code.
|
142
257
|
|
143
258
|
To trace any Ruby code, you can use the `Datadog.tracer.trace` method:
|
144
259
|
|
@@ -156,12 +271,13 @@ And `options` is an optional `Hash` that accepts the following parameters:
|
|
156
271
|
|
157
272
|
| Key | Type | Description | Default |
|
158
273
|
| --- | --- | --- | --- |
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
274
|
+
| `service` | `String` | The service name which this span belongs (e.g. `'my-web-service'`) | Tracer `default-service`, `$PROGRAM_NAME` or `'ruby'` |
|
275
|
+
| `resource` | `String` | Name of the resource or action being operated on. Traces with the same resource value will be grouped together for the purpose of metrics (but still independently viewable.) Usually domain specific, such as a URL, query, request, etc. (e.g. `'Article#submit'`, `http://example.com/articles/list`.) | `name` of Span. |
|
276
|
+
| `span_type` | `String` | The type of the span (such as `'http'`, `'db'`, etc.) | `nil` |
|
277
|
+
| `child_of` | `Datadog::Span` / `Datadog::Context` | Parent for this span. If not provided, will automatically become current active span. | `nil` |
|
278
|
+
| `start_time` | `Time` | When the span actually starts. Useful when tracing events that have already happened. | `Time.now` |
|
279
|
+
| `tags` | `Hash` | Extra tags which should be added to the span. | `{}` |
|
280
|
+
| `on_error` | `Proc` | Handler invoked when a block is provided to trace, and it raises an error. Provided `span` and `error` as arguments. Sets error on the span by default. | `proc { |span, error| span.set_error(error) unless span.nil? }` |
|
165
281
|
|
166
282
|
It's highly recommended you set both `service` and `resource` at a minimum. Spans without a `service` or `resource` as `nil` will be discarded by the Datadog agent.
|
167
283
|
|
@@ -187,14 +303,14 @@ get '/posts' do
|
|
187
303
|
end
|
188
304
|
```
|
189
305
|
|
190
|
-
|
306
|
+
### Asynchronous tracing
|
191
307
|
|
192
308
|
It might not always be possible to wrap `Datadog.tracer.trace` around a block of code. Some event or notification based instrumentation might only notify you when an event begins or ends.
|
193
309
|
|
194
310
|
To trace these operations, you can trace code asynchronously by calling `Datadog.tracer.trace` without a block:
|
195
311
|
|
196
312
|
```ruby
|
197
|
-
# Some instrumentation framework calls this after an event
|
313
|
+
# Some instrumentation framework calls this after an event finishes...
|
198
314
|
def db_query(start, finish, query)
|
199
315
|
span = Datadog.tracer.trace('database.query')
|
200
316
|
span.resource = query
|
@@ -226,17 +342,26 @@ def finish(name, id, payload)
|
|
226
342
|
end
|
227
343
|
end
|
228
344
|
```
|
229
|
-
|
345
|
+
### Enriching traces from nested methods
|
230
346
|
|
231
|
-
You can tag additional information to current active span from any method. Note however that if the method is called and there is no span currently active `active_span` will be nil.
|
347
|
+
You can tag additional information to the current active span from any method. Note however that if the method is called and there is no span currently active `active_span` will be nil.
|
232
348
|
|
233
349
|
```ruby
|
234
350
|
# e.g. adding tag to active span
|
235
|
-
|
351
|
+
|
236
352
|
current_span = Datadog.tracer.active_span
|
237
353
|
current_span.set_tag('my_tag', 'my_value') unless current_span.nil?
|
238
354
|
```
|
239
355
|
|
356
|
+
You can also get the root span of the current active trace using the `active_root_span` method. This method will return `nil` if there is no active trace.
|
357
|
+
|
358
|
+
```ruby
|
359
|
+
# e.g. adding tag to active root span
|
360
|
+
|
361
|
+
current_root_span = Datadog.tracer.active_root_span
|
362
|
+
current_root_span.set_tag('my_tag', 'my_value') unless current_root_span.nil?
|
363
|
+
```
|
364
|
+
|
240
365
|
## Integration instrumentation
|
241
366
|
|
242
367
|
Many popular libraries and frameworks are supported out-of-the-box, which can be auto-instrumented. Although they are not activated automatically, they can be easily activated and configured by using the `Datadog.configure` API:
|
@@ -252,33 +377,137 @@ end
|
|
252
377
|
|
253
378
|
For a list of available integrations, and their configuration options, please refer to the following:
|
254
379
|
|
255
|
-
| Name
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
380
|
+
| Name | Key | Versions Supported: MRI | Versions Supported: JRuby | How to configure | Gem source |
|
381
|
+
| ------------------------ | -------------------------- | ------------------------ | --------------------------| ----------------------------------- | ------------------------------------------------------------------------------ |
|
382
|
+
| Action Cable | `action_cable` | `>= 5.0` | `>= 5.0` | *[Link](#action-cable)* | *[Link](https://github.com/rails/rails/tree/master/actioncable)* |
|
383
|
+
| Action View | `action_view` | `>= 3.0` | `>= 3.0` | *[Link](#action-view)* | *[Link](https://github.com/rails/rails/tree/master/actionview)* |
|
384
|
+
| Active Model Serializers | `active_model_serializers` | `>= 0.9` | `>= 0.9` | *[Link](#active-model-serializers)* | *[Link](https://github.com/rails-api/active_model_serializers)* |
|
385
|
+
| Action Pack | `action_pack` | `>= 3.0` | `>= 3.0` | *[Link](#action-pack)* | *[Link](https://github.com/rails/rails/tree/master/actionpack)* |
|
386
|
+
| Active Record | `active_record` | `>= 3.0` | `>= 3.0` | *[Link](#active-record)* | *[Link](https://github.com/rails/rails/tree/master/activerecord)* |
|
387
|
+
| Active Support | `active_support` | `>= 3.0` | `>= 3.0` | *[Link](#active-support)* | *[Link](https://github.com/rails/rails/tree/master/activesupport)* |
|
388
|
+
| AWS | `aws` | `>= 2.0` | `>= 2.0` | *[Link](#aws)* | *[Link](https://github.com/aws/aws-sdk-ruby)* |
|
389
|
+
| Concurrent Ruby | `concurrent_ruby` | `>= 0.9` | `>= 0.9` | *[Link](#concurrent-ruby)* | *[Link](https://github.com/ruby-concurrency/concurrent-ruby)* |
|
390
|
+
| Cucumber | `cucumber` | `>= 3.0` | `>= 1.7.16` | *[Link](#cucumber)* | *[Link](https://github.com/cucumber/cucumber-ruby)* |
|
391
|
+
| Dalli | `dalli` | `>= 2.0` | `>= 2.0` | *[Link](#dalli)* | *[Link](https://github.com/petergoldstein/dalli)* |
|
392
|
+
| DelayedJob | `delayed_job` | `>= 4.1` | `>= 4.1` | *[Link](#delayedjob)* | *[Link](https://github.com/collectiveidea/delayed_job)* |
|
393
|
+
| Elasticsearch | `elasticsearch` | `>= 1.0` | `>= 1.0` | *[Link](#elasticsearch)* | *[Link](https://github.com/elastic/elasticsearch-ruby)* |
|
394
|
+
| Ethon | `ethon` | `>= 0.11` | `>= 0.11` | *[Link](#ethon)* | *[Link](https://github.com/typhoeus/ethon)* |
|
395
|
+
| Excon | `excon` | `>= 0.50` | `>= 0.50` | *[Link](#excon)* | *[Link](https://github.com/excon/excon)* |
|
396
|
+
| Faraday | `faraday` | `>= 0.14` | `>= 0.14` | *[Link](#faraday)* | *[Link](https://github.com/lostisland/faraday)* |
|
397
|
+
| Grape | `grape` | `>= 1.0` | `>= 1.0` | *[Link](#grape)* | *[Link](https://github.com/ruby-grape/grape)* |
|
398
|
+
| GraphQL | `graphql` | `>= 1.7.9` | `>= 1.7.9` | *[Link](#graphql)* | *[Link](https://github.com/rmosolgo/graphql-ruby)* |
|
399
|
+
| gRPC | `grpc` | `>= 1.7` | *gem not available* | *[Link](#grpc)* | *[Link](https://github.com/grpc/grpc/tree/master/src/rubyc)* |
|
400
|
+
| http.rb | `httprb` | `>= 2.0` | `>= 2.0` | *[Link](#http-rb)* | *[Link](https://github.com/httprb/http)* |
|
401
|
+
| httpclient | `httpclient` | `>= 2.2` | `>= 2.2` | *[Link](#httpclient)* | *[Link](https://github.com/nahi/httpclient)* |
|
402
|
+
| httpx | `httpx` | `>= 0.11` | `>= 0.11` | *[Link](#httpx)* | *[Link](https://gitlab.com/honeyryderchuck/httpx)* |
|
403
|
+
| Kafka | `ruby-kafka` | `>= 0.7.10` | `>= 0.7.10` | *[Link](#kafka)* | *[Link](https://github.com/zendesk/ruby-kafka)* |
|
404
|
+
| MongoDB | `mongo` | `>= 2.1` | `>= 2.1` | *[Link](#mongodb)* | *[Link](https://github.com/mongodb/mongo-ruby-driver)* |
|
405
|
+
| MySQL2 | `mysql2` | `>= 0.3.21` | *gem not available* | *[Link](#mysql2)* | *[Link](https://github.com/brianmario/mysql2)* |
|
406
|
+
| Net/HTTP | `http` | *(Any supported Ruby)* | *(Any supported Ruby)* | *[Link](#nethttp)* | *[Link](https://ruby-doc.org/stdlib-2.4.0/libdoc/net/http/rdoc/Net/HTTP.html)* |
|
407
|
+
| Presto | `presto` | `>= 0.5.14` | `>= 0.5.14` | *[Link](#presto)* | *[Link](https://github.com/treasure-data/presto-client-ruby)* |
|
408
|
+
| Qless | `qless` | `>= 0.10.0` | `>= 0.10.0` | *[Link](#qless)* | *[Link](https://github.com/seomoz/qless)* |
|
409
|
+
| Que | `que` | `>= 1.0.0.beta2` | `>= 1.0.0.beta2` | *[Link](#que)* | *[Link](https://github.com/que-rb/que)* |
|
410
|
+
| Racecar | `racecar` | `>= 0.3.5` | `>= 0.3.5` | *[Link](#racecar)* | *[Link](https://github.com/zendesk/racecar)* |
|
411
|
+
| Rack | `rack` | `>= 1.1` | `>= 1.1` | *[Link](#rack)* | *[Link](https://github.com/rack/rack)* |
|
412
|
+
| Rails | `rails` | `>= 3.0` | `>= 3.0` | *[Link](#rails)* | *[Link](https://github.com/rails/rails)* |
|
413
|
+
| Rake | `rake` | `>= 12.0` | `>= 12.0` | *[Link](#rake)* | *[Link](https://github.com/ruby/rake)* |
|
414
|
+
| Redis | `redis` | `>= 3.2` | `>= 3.2` | *[Link](#redis)* | *[Link](https://github.com/redis/redis-rb)* |
|
415
|
+
| Resque | `resque` | `>= 1.0` | `>= 1.0` | *[Link](#resque)* | *[Link](https://github.com/resque/resque)* |
|
416
|
+
| Rest Client | `rest-client` | `>= 1.8` | `>= 1.8` | *[Link](#rest-client)* | *[Link](https://github.com/rest-client/rest-client)* |
|
417
|
+
| RSpec | `rspec`. | `>= 3.0.0` | `>= 3.0.0` | *[Link](#rspec)*. | *[Link](https://github.com/rspec/rspec)* |
|
418
|
+
| Sequel | `sequel` | `>= 3.41` | `>= 3.41` | *[Link](#sequel)* | *[Link](https://github.com/jeremyevans/sequel)* |
|
419
|
+
| Shoryuken | `shoryuken` | `>= 3.2` | `>= 3.2` | *[Link](#shoryuken)* | *[Link](https://github.com/phstc/shoryuken)* |
|
420
|
+
| Sidekiq | `sidekiq` | `>= 3.5.4` | `>= 3.5.4` | *[Link](#sidekiq)* | *[Link](https://github.com/mperham/sidekiq)* |
|
421
|
+
| Sinatra | `sinatra` | `>= 1.4` | `>= 1.4` | *[Link](#sinatra)* | *[Link](https://github.com/sinatra/sinatra)* |
|
422
|
+
| Sneakers | `sneakers` | `>= 2.12.0` | `>= 2.12.0` | *[Link](#sneakers)* | *[Link](https://github.com/jondot/sneakers)* |
|
423
|
+
| Sucker Punch | `sucker_punch` | `>= 2.0` | `>= 2.0` | *[Link](#sucker-punch)* | *[Link](https://github.com/brandonhilkert/sucker_punch)* |
|
424
|
+
|
425
|
+
### Action Cable
|
426
|
+
|
427
|
+
The Action Cable integration traces broadcast messages and channel actions.
|
428
|
+
|
429
|
+
You can enable it through `Datadog.configure`:
|
430
|
+
|
431
|
+
```ruby
|
432
|
+
require 'ddtrace'
|
433
|
+
|
434
|
+
Datadog.configure do |c|
|
435
|
+
c.use :action_cable, options
|
436
|
+
end
|
437
|
+
```
|
438
|
+
|
439
|
+
Where `options` is an optional `Hash` that accepts the following parameters:
|
440
|
+
|
441
|
+
| Key | Description | Default |
|
442
|
+
| --- | ----------- | ------- |
|
443
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `false` |
|
444
|
+
| `service_name` | Service name used for `action_cable` instrumentation | `'action_cable'` |
|
445
|
+
|
446
|
+
### Action View
|
447
|
+
|
448
|
+
Most of the time, Active Support is set up as part of Rails, but it can be activated separately:
|
449
|
+
|
450
|
+
```ruby
|
451
|
+
require 'actionview'
|
452
|
+
require 'ddtrace'
|
453
|
+
|
454
|
+
Datadog.configure do |c|
|
455
|
+
c.use :action_view, options
|
456
|
+
end
|
457
|
+
```
|
458
|
+
|
459
|
+
Where `options` is an optional `Hash` that accepts the following parameters:
|
460
|
+
|
461
|
+
| Key | Description | Default |
|
462
|
+
| ---| --- | --- |
|
463
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `false` |
|
464
|
+
| `service_name` | Service name used for rendering instrumentation. | `action_view` |
|
465
|
+
| `template_base_path` | Used when the template name is parsed. If you don't store your templates in the `views/` folder, you may need to change this value | `'views/'` |
|
466
|
+
|
467
|
+
### Active Model Serializers
|
468
|
+
|
469
|
+
The Active Model Serializers integration traces the `serialize` event for version 0.9+ and the `render` event for version 0.10+.
|
470
|
+
|
471
|
+
```ruby
|
472
|
+
require 'active_model_serializers'
|
473
|
+
require 'ddtrace'
|
474
|
+
|
475
|
+
Datadog.configure do |c|
|
476
|
+
c.use :active_model_serializers, options
|
477
|
+
end
|
478
|
+
|
479
|
+
my_object = MyModel.new(name: 'my object')
|
480
|
+
ActiveModelSerializers::SerializableResource.new(test_obj).serializable_hash
|
481
|
+
```
|
482
|
+
|
483
|
+
| Key | Description | Default |
|
484
|
+
| --- | ----------- | ------- |
|
485
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `false` |
|
486
|
+
| `service_name` | Service name used for `active_model_serializers` instrumentation. | `'active_model_serializers'` |
|
487
|
+
|
488
|
+
### Action Pack
|
489
|
+
|
490
|
+
Most of the time, Action Pack is set up as part of Rails, but it can be activated separately:
|
491
|
+
|
492
|
+
```ruby
|
493
|
+
require 'actionpack'
|
494
|
+
require 'ddtrace'
|
495
|
+
|
496
|
+
Datadog.configure do |c|
|
497
|
+
c.use :action_pack, options
|
498
|
+
end
|
499
|
+
```
|
500
|
+
|
501
|
+
Where `options` is an optional `Hash` that accepts the following parameters:
|
502
|
+
|
503
|
+
| Key | Description | Default |
|
504
|
+
| ---| --- | --- |
|
505
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `false` |
|
506
|
+
| `service_name` | Service name used for rendering instrumentation. | `action_pack` |
|
278
507
|
|
279
508
|
### Active Record
|
280
509
|
|
281
|
-
Most of the time, Active Record is set up as part of a web framework (Rails, Sinatra...) however it can be set up alone:
|
510
|
+
Most of the time, Active Record is set up as part of a web framework (Rails, Sinatra...) however, it can be set up alone:
|
282
511
|
|
283
512
|
```ruby
|
284
513
|
require 'tmpdir'
|
@@ -300,9 +529,95 @@ end
|
|
300
529
|
Where `options` is an optional `Hash` that accepts the following parameters:
|
301
530
|
|
302
531
|
| Key | Description | Default |
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
532
|
+
| ---| --- | --- |
|
533
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to the global setting, `false` for off. | `false` |
|
534
|
+
| `orm_service_name` | Service name used for the mapping portion of query results to ActiveRecord objects. Inherits service name from parent by default. | _parent.service_name_ (e.g. `'mysql2'`) |
|
535
|
+
| `service_name` | Service name used for database portion of `active_record` instrumentation. | Name of database adapter (e.g. `'mysql2'`) |
|
536
|
+
|
537
|
+
**Configuring trace settings per database**
|
538
|
+
|
539
|
+
You can configure trace settings per database connection by using the `describes` option:
|
540
|
+
|
541
|
+
```ruby
|
542
|
+
# Provide a `:describes` option with a connection key.
|
543
|
+
# Any of the following keys are acceptable and equivalent to one another.
|
544
|
+
# If a block is provided, it yields a Settings object that
|
545
|
+
# accepts any of the configuration options listed above.
|
546
|
+
|
547
|
+
Datadog.configure do |c|
|
548
|
+
# Symbol matching your database connection in config/database.yml
|
549
|
+
# Only available if you are using Rails with ActiveRecord.
|
550
|
+
c.use :active_record, describes: :secondary_database, service_name: 'secondary-db'
|
551
|
+
|
552
|
+
# Block configuration pattern.
|
553
|
+
c.use :active_record, describes: :secondary_database do |second_db|
|
554
|
+
second_db.service_name = 'secondary-db'
|
555
|
+
end
|
556
|
+
|
557
|
+
# Connection string with the following connection settings:
|
558
|
+
# adapter, username, host, port, database
|
559
|
+
# Other fields are ignored.
|
560
|
+
c.use :active_record, describes: 'mysql2://root@127.0.0.1:3306/mysql', service_name: 'secondary-db'
|
561
|
+
|
562
|
+
# Hash with following connection settings:
|
563
|
+
# adapter, username, host, port, database
|
564
|
+
# Other fields are ignored.
|
565
|
+
c.use :active_record, describes: {
|
566
|
+
adapter: 'mysql2',
|
567
|
+
host: '127.0.0.1',
|
568
|
+
port: '3306',
|
569
|
+
database: 'mysql',
|
570
|
+
username: 'root'
|
571
|
+
},
|
572
|
+
service_name: 'secondary-db'
|
573
|
+
end
|
574
|
+
```
|
575
|
+
|
576
|
+
You can also create configurations based on partial matching of database connection fields:
|
577
|
+
|
578
|
+
```ruby
|
579
|
+
Datadog.configure do |c|
|
580
|
+
# Matches any connection on host `127.0.0.1`.
|
581
|
+
c.use :active_record, describes: { host: '127.0.0.1' }, service_name: 'local-db'
|
582
|
+
|
583
|
+
# Matches any `mysql2` connection.
|
584
|
+
c.use :active_record, describes: { adapter: 'mysql2'}, service_name: 'mysql-db'
|
585
|
+
|
586
|
+
# Matches any `mysql2` connection to the `reports` database.
|
587
|
+
#
|
588
|
+
# In case of multiple matching `describe` configurations, the latest one applies.
|
589
|
+
# In this case a connection with both adapter `mysql` and database `reports`
|
590
|
+
# will be configured `service_name: 'reports-db'`, not `service_name: 'mysql-db'`.
|
591
|
+
c.use :active_record, describes: { adapter: 'mysql2', database: 'reports'}, service_name: 'reports-db'
|
592
|
+
end
|
593
|
+
```
|
594
|
+
|
595
|
+
When multiple `describes` configurations match a connection, the latest configured rule that matches will be applied.
|
596
|
+
|
597
|
+
If ActiveRecord traces an event that uses a connection that matches a key defined by `describes`, it will use the trace settings assigned to that connection. If the connection does not match any of the described connections, it will use default settings defined by `c.use :active_record` instead.
|
598
|
+
|
599
|
+
### Active Support
|
600
|
+
|
601
|
+
Most of the time, Active Support is set up as part of Rails, but it can be activated separately:
|
602
|
+
|
603
|
+
```ruby
|
604
|
+
require 'activesupport'
|
605
|
+
require 'ddtrace'
|
606
|
+
|
607
|
+
Datadog.configure do |c|
|
608
|
+
c.use :active_support, options
|
609
|
+
end
|
610
|
+
|
611
|
+
cache = ActiveSupport::Cache::MemoryStore.new
|
612
|
+
cache.read('city')
|
613
|
+
```
|
614
|
+
|
615
|
+
Where `options` is an optional `Hash` that accepts the following parameters:
|
616
|
+
|
617
|
+
| Key | Description | Default |
|
618
|
+
| ---| --- | --- |
|
619
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `false` |
|
620
|
+
| `cache_service` | Service name used for caching with `active_support` instrumentation. | `active_support-cache` |
|
306
621
|
|
307
622
|
### AWS
|
308
623
|
|
@@ -316,27 +631,92 @@ Datadog.configure do |c|
|
|
316
631
|
c.use :aws, options
|
317
632
|
end
|
318
633
|
|
319
|
-
|
634
|
+
# Perform traced call
|
635
|
+
Aws::S3::Client.new.list_buckets
|
636
|
+
```
|
637
|
+
|
638
|
+
Where `options` is an optional `Hash` that accepts the following parameters:
|
639
|
+
|
640
|
+
| Key | Description | Default |
|
641
|
+
| --- | ----------- | ------- |
|
642
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `false` |
|
643
|
+
| `service_name` | Service name used for `aws` instrumentation | `'aws'` |
|
644
|
+
|
645
|
+
### Concurrent Ruby
|
646
|
+
|
647
|
+
The Concurrent Ruby integration adds support for context propagation when using `::Concurrent::Future`.
|
648
|
+
Making sure that code traced within the `Future#execute` will have correct parent set.
|
649
|
+
|
650
|
+
To activate your integration, use the `Datadog.configure` method:
|
651
|
+
|
652
|
+
```ruby
|
653
|
+
# Inside Rails initializer or equivalent
|
654
|
+
Datadog.configure do |c|
|
655
|
+
# Patches ::Concurrent::Future to use ExecutorService that propagates context
|
656
|
+
c.use :concurrent_ruby, options
|
657
|
+
end
|
658
|
+
|
659
|
+
# Pass context into code executed within Concurrent::Future
|
660
|
+
Datadog.tracer.trace('outer') do
|
661
|
+
Concurrent::Future.execute { Datadog.tracer.trace('inner') { } }.wait
|
662
|
+
end
|
663
|
+
```
|
664
|
+
|
665
|
+
Where `options` is an optional `Hash` that accepts the following parameters:
|
666
|
+
|
667
|
+
| Key | Description | Default |
|
668
|
+
| --- | ----------- | ------- |
|
669
|
+
| `service_name` | Service name used for `concurrent-ruby` instrumentation | `'concurrent-ruby'` |
|
670
|
+
|
671
|
+
### Cucumber
|
672
|
+
|
673
|
+
Cucumber integration will trace all executions of scenarios and steps when using `cucumber` framework.
|
674
|
+
|
675
|
+
To activate your integration, use the `Datadog.configure` method:
|
676
|
+
|
677
|
+
```ruby
|
678
|
+
require 'cucumber'
|
679
|
+
require 'ddtrace'
|
680
|
+
|
681
|
+
# Configure default Cucumber integration
|
682
|
+
Datadog.configure do |c|
|
683
|
+
c.use :cucumber, options
|
684
|
+
end
|
685
|
+
|
686
|
+
# Example of how to attach tags from scenario to active span
|
687
|
+
Around do |scenario, block|
|
688
|
+
active_span = Datadog.configuration[:cucumber][:tracer].active_span
|
689
|
+
unless active_span.nil?
|
690
|
+
scenario.tags.filter { |tag| tag.include? ':' }.each do |tag|
|
691
|
+
active_span.set_tag(*tag.name.split(':', 2))
|
692
|
+
end
|
693
|
+
end
|
694
|
+
block.call
|
695
|
+
end
|
320
696
|
```
|
321
697
|
|
322
698
|
Where `options` is an optional `Hash` that accepts the following parameters:
|
323
699
|
|
324
700
|
| Key | Description | Default |
|
325
|
-
| --- |
|
326
|
-
|
|
701
|
+
| --- | ----------- | ------- |
|
702
|
+
| `enabled` | Defines whether Cucumber tests should be traced. Useful for temporarily disabling tracing. `true` or `false` | `true` |
|
703
|
+
| `service_name` | Service name used for `cucumber` instrumentation. | `'cucumber'` |
|
704
|
+
| `operation_name` | Operation name used for `cucumber` instrumentation. Useful if you want rename automatic trace metrics e.g. `trace.#{operation_name}.errors`. | `'cucumber.test'` |
|
327
705
|
|
328
706
|
### Dalli
|
329
707
|
|
330
|
-
Dalli integration will trace all calls to your
|
708
|
+
Dalli integration will trace all calls to your `memcached` server:
|
331
709
|
|
332
710
|
```ruby
|
333
711
|
require 'dalli'
|
334
712
|
require 'ddtrace'
|
335
713
|
|
714
|
+
# Configure default Dalli tracing behavior
|
336
715
|
Datadog.configure do |c|
|
337
|
-
c.use :dalli,
|
716
|
+
c.use :dalli, options
|
338
717
|
end
|
339
718
|
|
719
|
+
# Configure Dalli tracing behavior for single client
|
340
720
|
client = Dalli::Client.new('localhost:11211', options)
|
341
721
|
client.set('abc', 123)
|
342
722
|
```
|
@@ -344,12 +724,36 @@ client.set('abc', 123)
|
|
344
724
|
Where `options` is an optional `Hash` that accepts the following parameters:
|
345
725
|
|
346
726
|
| Key | Description | Default |
|
347
|
-
| --- |
|
348
|
-
|
|
727
|
+
| --- | ----------- | ------- |
|
728
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `false` |
|
729
|
+
| `service_name` | Service name used for `dalli` instrumentation | `'memcached'` |
|
730
|
+
|
731
|
+
### DelayedJob
|
732
|
+
|
733
|
+
The DelayedJob integration uses lifecycle hooks to trace the job executions and enqueues.
|
734
|
+
|
735
|
+
You can enable it through `Datadog.configure`:
|
736
|
+
|
737
|
+
```ruby
|
738
|
+
require 'ddtrace'
|
739
|
+
|
740
|
+
Datadog.configure do |c|
|
741
|
+
c.use :delayed_job, options
|
742
|
+
end
|
743
|
+
```
|
744
|
+
|
745
|
+
Where `options` is an optional `Hash` that accepts the following parameters:
|
746
|
+
|
747
|
+
| Key | Description | Default |
|
748
|
+
| --- | ----------- | ------- |
|
749
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `false` |
|
750
|
+
| `service_name` | Service name used for `DelayedJob` instrumentation | `'delayed_job'` |
|
751
|
+
| `client_service_name` | Service name used for client-side `DelayedJob` instrumentation | `'delayed_job-client'` |
|
752
|
+
| `error_handler` | Custom error handler invoked when a job raises an error. Provided `span` and `error` as arguments. Sets error on the span by default. Useful for ignoring transient errors. | `proc { |span, error| span.set_error(error) unless span.nil? }` |
|
349
753
|
|
350
|
-
###
|
754
|
+
### Elasticsearch
|
351
755
|
|
352
|
-
The Elasticsearch integration will trace any call to
|
756
|
+
The Elasticsearch integration will trace any call to `perform_request` in the `Client` object:
|
353
757
|
|
354
758
|
```ruby
|
355
759
|
require 'elasticsearch/transport'
|
@@ -359,7 +763,7 @@ Datadog.configure do |c|
|
|
359
763
|
c.use :elasticsearch, options
|
360
764
|
end
|
361
765
|
|
362
|
-
#
|
766
|
+
# Perform a query to Elasticsearch
|
363
767
|
client = Elasticsearch::Client.new url: 'http://127.0.0.1:9200'
|
364
768
|
response = client.perform_request 'GET', '_cluster/health'
|
365
769
|
```
|
@@ -367,9 +771,37 @@ response = client.perform_request 'GET', '_cluster/health'
|
|
367
771
|
Where `options` is an optional `Hash` that accepts the following parameters:
|
368
772
|
|
369
773
|
| Key | Description | Default |
|
370
|
-
| --- |
|
371
|
-
|
|
372
|
-
|
|
774
|
+
| --- | ----------- | ------- |
|
775
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `false` |
|
776
|
+
| `quantize` | Hash containing options for quantization. May include `:show` with an Array of keys to not quantize (or `:all` to skip quantization), or `:exclude` with Array of keys to exclude entirely. | `{}` |
|
777
|
+
| `service_name` | Service name used for `elasticsearch` instrumentation | `'elasticsearch'` |
|
778
|
+
|
779
|
+
### Ethon
|
780
|
+
|
781
|
+
The `ethon` integration will trace any HTTP request through `Easy` or `Multi` objects. Note that this integration also supports `Typhoeus` library which is based on `Ethon`.
|
782
|
+
|
783
|
+
```ruby
|
784
|
+
require 'ddtrace'
|
785
|
+
|
786
|
+
Datadog.configure do |c|
|
787
|
+
c.use :ethon, options
|
788
|
+
|
789
|
+
# optionally, specify a different service name for hostnames matching a regex
|
790
|
+
c.use :ethon, describes: /user-[^.]+\.example\.com/ do |ethon|
|
791
|
+
ethon.service_name = 'user.example.com'
|
792
|
+
ethon.split_by_domain = false # Only necessary if split_by_domain is true by default
|
793
|
+
end
|
794
|
+
end
|
795
|
+
```
|
796
|
+
|
797
|
+
Where `options` is an optional `Hash` that accepts the following parameters:
|
798
|
+
|
799
|
+
| Key | Description | Default |
|
800
|
+
| --- | ----------- | ------- |
|
801
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `false` |
|
802
|
+
| `distributed_tracing` | Enables [distributed tracing](#distributed-tracing) | `true` |
|
803
|
+
| `service_name` | Service name for `ethon` instrumentation. | `'ethon'` |
|
804
|
+
| `split_by_domain` | Uses the request domain as the service name when set to `true`. | `false` |
|
373
805
|
|
374
806
|
### Excon
|
375
807
|
|
@@ -381,7 +813,13 @@ require 'ddtrace'
|
|
381
813
|
|
382
814
|
# Configure default Excon tracing behavior
|
383
815
|
Datadog.configure do |c|
|
384
|
-
c.use :excon,
|
816
|
+
c.use :excon, options
|
817
|
+
|
818
|
+
# optionally, specify a different service name for hostnames matching a regex
|
819
|
+
c.use :excon, describes: /user-[^.]+\.example\.com/ do |excon|
|
820
|
+
excon.service_name = 'user.example.com'
|
821
|
+
excon.split_by_domain = false # Only necessary if split_by_domain is true by default
|
822
|
+
end
|
385
823
|
end
|
386
824
|
|
387
825
|
connection = Excon.new('https://example.com')
|
@@ -391,12 +829,12 @@ connection.get
|
|
391
829
|
Where `options` is an optional `Hash` that accepts the following parameters:
|
392
830
|
|
393
831
|
| Key | Description | Default |
|
394
|
-
| --- |
|
832
|
+
| --- | ----------- | ------- |
|
833
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `false` |
|
834
|
+
| `distributed_tracing` | Enables [distributed tracing](#distributed-tracing) | `true` |
|
835
|
+
| `error_handler` | A `Proc` that accepts a `response` parameter. If it evaluates to a *truthy* value, the trace span is marked as an error. By default only sets 5XX responses as errors. | `nil` |
|
395
836
|
| `service_name` | Service name for Excon instrumentation. When provided to middleware for a specific connection, it applies only to that connection object. | `'excon'` |
|
396
837
|
| `split_by_domain` | Uses the request domain as the service name when set to `true`. | `false` |
|
397
|
-
| `distributed_tracing` | Enables [distributed tracing](#distributed-tracing) | `false` |
|
398
|
-
| `error_handler` | A `Proc` that accepts a `response` parameter. If it evaluates to a *truthy* value, the trace span is marked as an error. By default only sets 5XX responses as errors. | `nil` |
|
399
|
-
| `tracer` | A `Datadog::Tracer` instance used to instrument the application. Usually you don't need to set that. | `Datadog.tracer` |
|
400
838
|
|
401
839
|
**Configuring connections to use different settings**
|
402
840
|
|
@@ -431,10 +869,18 @@ The `faraday` integration is available through the `ddtrace` middleware:
|
|
431
869
|
require 'faraday'
|
432
870
|
require 'ddtrace'
|
433
871
|
|
872
|
+
# Configure default Faraday tracing behavior
|
434
873
|
Datadog.configure do |c|
|
435
|
-
c.use :faraday,
|
874
|
+
c.use :faraday, options
|
875
|
+
|
876
|
+
# optionally, specify a different service name for hostnames matching a regex
|
877
|
+
c.use :faraday, describes: /user-[^.]+\.example\.com/ do |faraday|
|
878
|
+
faraday.service_name = 'user.example.com'
|
879
|
+
faraday.split_by_domain = false # Only necessary if split_by_domain is true by default
|
880
|
+
end
|
436
881
|
end
|
437
882
|
|
883
|
+
# In case you want to override the global configuration for a certain client instance
|
438
884
|
connection = Faraday.new('https://example.com') do |builder|
|
439
885
|
builder.use(:ddtrace, options)
|
440
886
|
builder.adapter Faraday.default_adapter
|
@@ -446,18 +892,121 @@ connection.get('/foo')
|
|
446
892
|
Where `options` is an optional `Hash` that accepts the following parameters:
|
447
893
|
|
448
894
|
| Key | Description | Default |
|
449
|
-
| --- |
|
895
|
+
| --- | ----------- | ------- |
|
896
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `false` |
|
897
|
+
| `distributed_tracing` | Enables [distributed tracing](#distributed-tracing) | `true` |
|
898
|
+
| `error_handler` | A `Proc` that accepts a `response` parameter. If it evaluates to a *truthy* value, the trace span is marked as an error. By default only sets 5XX responses as errors. | `nil` |
|
450
899
|
| `service_name` | Service name for Faraday instrumentation. When provided to middleware for a specific connection, it applies only to that connection object. | `'faraday'` |
|
451
900
|
| `split_by_domain` | Uses the request domain as the service name when set to `true`. | `false` |
|
452
|
-
|
453
|
-
|
454
|
-
|
901
|
+
|
902
|
+
### Grape
|
903
|
+
|
904
|
+
The Grape integration adds the instrumentation to Grape endpoints and filters. This integration can work side by side with other integrations like Rack and Rails.
|
905
|
+
|
906
|
+
To activate your integration, use the `Datadog.configure` method before defining your Grape application:
|
907
|
+
|
908
|
+
```ruby
|
909
|
+
# api.rb
|
910
|
+
require 'grape'
|
911
|
+
require 'ddtrace'
|
912
|
+
|
913
|
+
Datadog.configure do |c|
|
914
|
+
c.use :grape, options
|
915
|
+
end
|
916
|
+
|
917
|
+
# Then define your application
|
918
|
+
class RackTestingAPI < Grape::API
|
919
|
+
desc 'main endpoint'
|
920
|
+
get :success do
|
921
|
+
'Hello world!'
|
922
|
+
end
|
923
|
+
end
|
924
|
+
```
|
925
|
+
|
926
|
+
Where `options` is an optional `Hash` that accepts the following parameters:
|
927
|
+
|
928
|
+
| Key | Description | Default |
|
929
|
+
| --- | ----------- | ------- |
|
930
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `nil` |
|
931
|
+
| `enabled` | Defines whether Grape should be traced. Useful for temporarily disabling tracing. `true` or `false` | `true` |
|
932
|
+
| `service_name` | Service name used for `grape` instrumentation | `'grape'` |
|
933
|
+
| `error_statuses`| Defines a status code or range of status codes which should be marked as errors. `'404,405,500-599'` or `[404,405,'500-599']` | `nil` |
|
934
|
+
|
935
|
+
### GraphQL
|
936
|
+
|
937
|
+
The GraphQL integration activates instrumentation for GraphQL queries.
|
938
|
+
|
939
|
+
To activate your integration, use the `Datadog.configure` method:
|
940
|
+
|
941
|
+
```ruby
|
942
|
+
# Inside Rails initializer or equivalent
|
943
|
+
Datadog.configure do |c|
|
944
|
+
c.use :graphql, schemas: [YourSchema], options
|
945
|
+
end
|
946
|
+
|
947
|
+
# Then run a GraphQL query
|
948
|
+
YourSchema.execute(query, variables: {}, context: {}, operation_name: nil)
|
949
|
+
```
|
950
|
+
|
951
|
+
The `use :graphql` method accepts the following parameters. Additional options can be substituted in for `options`:
|
952
|
+
|
953
|
+
| Key | Description | Default |
|
954
|
+
| --- | ----------- | ------- |
|
955
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `nil` |
|
956
|
+
| `service_name` | Service name used for `graphql` instrumentation | `'ruby-graphql'` |
|
957
|
+
| `schemas` | Required. Array of `GraphQL::Schema` objects which to trace. Tracing will be added to all the schemas listed, using the options provided to this configuration. If you do not provide any, then tracing will not be activated. | `[]` |
|
958
|
+
|
959
|
+
**Manually configuring GraphQL schemas**
|
960
|
+
|
961
|
+
If you prefer to individually configure the tracer settings for a schema (e.g. you have multiple schemas with different service names), in the schema definition, you can add the following [using the GraphQL API](http://graphql-ruby.org/queries/tracing.html):
|
962
|
+
|
963
|
+
```ruby
|
964
|
+
# Class-based schema
|
965
|
+
class YourSchema < GraphQL::Schema
|
966
|
+
use(
|
967
|
+
GraphQL::Tracing::DataDogTracing,
|
968
|
+
service: 'graphql'
|
969
|
+
)
|
970
|
+
end
|
971
|
+
```
|
972
|
+
|
973
|
+
```ruby
|
974
|
+
# .define-style schema
|
975
|
+
YourSchema = GraphQL::Schema.define do
|
976
|
+
use(
|
977
|
+
GraphQL::Tracing::DataDogTracing,
|
978
|
+
service: 'graphql'
|
979
|
+
)
|
980
|
+
end
|
981
|
+
```
|
982
|
+
|
983
|
+
Or you can modify an already defined schema:
|
984
|
+
|
985
|
+
```ruby
|
986
|
+
# Class-based schema
|
987
|
+
YourSchema.use(
|
988
|
+
GraphQL::Tracing::DataDogTracing,
|
989
|
+
service: 'graphql'
|
990
|
+
)
|
991
|
+
```
|
992
|
+
|
993
|
+
```ruby
|
994
|
+
# .define-style schema
|
995
|
+
YourSchema.define do
|
996
|
+
use(
|
997
|
+
GraphQL::Tracing::DataDogTracing,
|
998
|
+
service: 'graphql'
|
999
|
+
)
|
1000
|
+
end
|
1001
|
+
```
|
1002
|
+
|
1003
|
+
Do *NOT* `use :graphql` in `Datadog.configure` if you choose to configure manually, as to avoid double tracing. These two means of configuring GraphQL tracing are considered mutually exclusive.
|
455
1004
|
|
456
1005
|
### gRPC
|
457
1006
|
|
458
|
-
The `grpc` integration adds both client and server interceptors, which run as middleware
|
1007
|
+
The `grpc` integration adds both client and server interceptors, which run as middleware before executing the service's remote procedure call. As gRPC applications are often distributed, the integration shares trace information between client and server.
|
459
1008
|
|
460
|
-
To setup your integration, use the
|
1009
|
+
To setup your integration, use the `Datadog.configure` method like so:
|
461
1010
|
|
462
1011
|
```ruby
|
463
1012
|
require 'grpc'
|
@@ -467,19 +1016,26 @@ Datadog.configure do |c|
|
|
467
1016
|
c.use :grpc, options
|
468
1017
|
end
|
469
1018
|
|
470
|
-
#
|
471
|
-
|
472
|
-
# server side
|
1019
|
+
# Server side
|
473
1020
|
server = GRPC::RpcServer.new
|
474
1021
|
server.add_http2_port('localhost:50051', :this_port_is_insecure)
|
475
1022
|
server.handle(Demo)
|
476
1023
|
server.run_till_terminated
|
477
1024
|
|
478
|
-
#
|
1025
|
+
# Client side
|
479
1026
|
client = Demo.rpc_stub_class.new('localhost:50051', :this_channel_is_insecure)
|
480
1027
|
client.my_endpoint(DemoMessage.new(contents: 'hello!'))
|
481
1028
|
```
|
482
1029
|
|
1030
|
+
Where `options` is an optional `Hash` that accepts the following parameters:
|
1031
|
+
|
1032
|
+
| Key | Description | Default |
|
1033
|
+
| --- | ----------- | ------- |
|
1034
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `false` |
|
1035
|
+
| `service_name` | Service name used for `grpc` instrumentation | `'grpc'` |
|
1036
|
+
|
1037
|
+
**Configuring clients to use different settings**
|
1038
|
+
|
483
1039
|
In situations where you have multiple clients calling multiple distinct services, you may pass the Datadog interceptor directly, like so
|
484
1040
|
|
485
1041
|
```ruby
|
@@ -494,160 +1050,277 @@ alternate_client = Demo::Echo::Service.rpc_stub_class.new(
|
|
494
1050
|
)
|
495
1051
|
```
|
496
1052
|
|
497
|
-
The integration will ensure that the
|
1053
|
+
The integration will ensure that the `configured_interceptor` establishes a unique tracing setup for that client instance.
|
498
1054
|
|
499
|
-
|
1055
|
+
### http.rb
|
500
1056
|
|
501
|
-
|
502
|
-
| --- | --- | --- |
|
503
|
-
| ``service_name`` | Service name used for `grpc` instrumentation | grpc |
|
504
|
-
| ``tracer`` | Datadog tracer used for `grpc` instrumentation | Datadog.tracer |
|
1057
|
+
The http.rb integration will trace any HTTP call using the Http.rb gem.
|
505
1058
|
|
506
|
-
|
1059
|
+
```ruby
|
1060
|
+
require 'http'
|
1061
|
+
require 'ddtrace'
|
1062
|
+
Datadog.configure do |c|
|
1063
|
+
c.use :httprb, options
|
1064
|
+
# optionally, specify a different service name for hostnames matching a regex
|
1065
|
+
c.use :httprb, describes: /user-[^.]+\.example\.com/ do |httprb|
|
1066
|
+
httprb.service_name = 'user.example.com'
|
1067
|
+
httprb.split_by_domain = false # Only necessary if split_by_domain is true by default
|
1068
|
+
end
|
1069
|
+
end
|
1070
|
+
```
|
507
1071
|
|
508
|
-
|
1072
|
+
Where `options` is an optional `Hash` that accepts the following parameters:
|
1073
|
+
|
1074
|
+
| Key | Description | Default |
|
1075
|
+
| --- | ----------- | ------- |
|
1076
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `false` |
|
1077
|
+
| `distributed_tracing` | Enables [distributed tracing](#distributed-tracing) | `true` |
|
1078
|
+
| `service_name` | Service name for `httprb` instrumentation. | `'httprb'` |
|
1079
|
+
| `split_by_domain` | Uses the request domain as the service name when set to `true`. | `false` |
|
509
1080
|
|
510
|
-
|
1081
|
+
### httpclient
|
1082
|
+
|
1083
|
+
The httpclient integration will trace any HTTP call using the httpclient gem.
|
511
1084
|
|
512
1085
|
```ruby
|
513
|
-
|
514
|
-
require 'grape'
|
1086
|
+
require 'httpclient'
|
515
1087
|
require 'ddtrace'
|
516
|
-
|
517
1088
|
Datadog.configure do |c|
|
518
|
-
c.use :
|
1089
|
+
c.use :httpclient, options
|
1090
|
+
# optionally, specify a different service name for hostnames matching a regex
|
1091
|
+
c.use :httpclient, describes: /user-[^.]+\.example\.com/ do |httpclient|
|
1092
|
+
httpclient.service_name = 'user.example.com'
|
1093
|
+
httpclient.split_by_domain = false # Only necessary if split_by_domain is true by default
|
1094
|
+
end
|
519
1095
|
end
|
1096
|
+
```
|
520
1097
|
|
521
|
-
|
522
|
-
|
523
|
-
|
524
|
-
|
525
|
-
|
1098
|
+
Where `options` is an optional `Hash` that accepts the following parameters:
|
1099
|
+
|
1100
|
+
| Key | Description | Default |
|
1101
|
+
| --- | ----------- | ------- |
|
1102
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `false` |
|
1103
|
+
| `distributed_tracing` | Enables [distributed tracing](#distributed-tracing) | `true` |
|
1104
|
+
| `service_name` | Service name for `httpclient` instrumentation. | `'httpclient'` |
|
1105
|
+
| `split_by_domain` | Uses the request domain as the service name when set to `true`. | `false` |
|
1106
|
+
|
1107
|
+
### httpx
|
1108
|
+
|
1109
|
+
`httpx` maintains its [own integration with `ddtrace`](https://honeyryderchuck.gitlab.io/httpx/wiki/Datadog-Adapter):
|
1110
|
+
|
1111
|
+
```ruby
|
1112
|
+
require "ddtrace"
|
1113
|
+
require "httpx/adapters/datadog"
|
1114
|
+
|
1115
|
+
Datadog.configure do |c|
|
1116
|
+
c.use :httpx
|
1117
|
+
|
1118
|
+
# optionally, specify a different service name for hostnames matching a regex
|
1119
|
+
c.use :httpx, describes: /user-[^.]+\.example\.com/ do |http|
|
1120
|
+
http.service_name = 'user.example.com'
|
1121
|
+
http.split_by_domain = false # Only necessary if split_by_domain is true by default
|
526
1122
|
end
|
527
1123
|
end
|
528
1124
|
```
|
529
1125
|
|
1126
|
+
### Kafka
|
1127
|
+
|
1128
|
+
The Kafka integration provides tracing of the `ruby-kafka` gem:
|
1129
|
+
|
1130
|
+
You can enable it through `Datadog.configure`:
|
1131
|
+
|
1132
|
+
```ruby
|
1133
|
+
require 'active_support/notifications' # required to enable 'ruby-kafka' instrumentation
|
1134
|
+
require 'kafka'
|
1135
|
+
require 'ddtrace'
|
1136
|
+
|
1137
|
+
Datadog.configure do |c|
|
1138
|
+
c.use :kafka, options
|
1139
|
+
end
|
1140
|
+
```
|
1141
|
+
|
530
1142
|
Where `options` is an optional `Hash` that accepts the following parameters:
|
531
1143
|
|
532
1144
|
| Key | Description | Default |
|
533
|
-
| --- |
|
534
|
-
|
|
535
|
-
|
536
|
-
|
1145
|
+
| --- | ----------- | ------- |
|
1146
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `false` |
|
1147
|
+
| `service_name` | Service name used for `kafka` instrumentation | `'kafka'` |
|
1148
|
+
| `tracer` | `Datadog::Tracer` used to perform instrumentation. Usually you don't need to set this. | `Datadog.tracer` |
|
537
1149
|
|
538
|
-
|
1150
|
+
### MongoDB
|
539
1151
|
|
540
|
-
|
1152
|
+
The integration traces any `Command` that is sent from the [MongoDB Ruby Driver](https://github.com/mongodb/mongo-ruby-driver) to a MongoDB cluster. By extension, Object Document Mappers (ODM) such as Mongoid are automatically instrumented if they use the official Ruby driver. To activate the integration, simply:
|
541
1153
|
|
542
1154
|
```ruby
|
543
|
-
|
1155
|
+
require 'mongo'
|
1156
|
+
require 'ddtrace'
|
1157
|
+
|
544
1158
|
Datadog.configure do |c|
|
545
|
-
c.use :
|
546
|
-
service_name: 'graphql',
|
547
|
-
schemas: [YourSchema]
|
1159
|
+
c.use :mongo, options
|
548
1160
|
end
|
549
1161
|
|
550
|
-
#
|
551
|
-
|
1162
|
+
# Create a MongoDB client and use it as usual
|
1163
|
+
client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'artists')
|
1164
|
+
collection = client[:people]
|
1165
|
+
collection.insert_one({ name: 'Steve' })
|
1166
|
+
|
1167
|
+
# In case you want to override the global configuration for a certain client instance
|
1168
|
+
Datadog.configure(client, options)
|
552
1169
|
```
|
553
1170
|
|
554
|
-
|
1171
|
+
Where `options` is an optional `Hash` that accepts the following parameters:
|
555
1172
|
|
556
1173
|
| Key | Description | Default |
|
557
|
-
| --- |
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
1174
|
+
| --- | ----------- | ------- |
|
1175
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `false` |
|
1176
|
+
| `quantize` | Hash containing options for quantization. May include `:show` with an Array of keys to not quantize (or `:all` to skip quantization), or `:exclude` with Array of keys to exclude entirely. | `{ show: [:collection, :database, :operation] }` |
|
1177
|
+
| `service_name` | Service name used for `mongo` instrumentation | `'mongodb'` |
|
561
1178
|
|
562
|
-
|
1179
|
+
### MySQL2
|
563
1180
|
|
564
|
-
|
1181
|
+
The MySQL2 integration traces any SQL command sent through `mysql2` gem.
|
565
1182
|
|
566
1183
|
```ruby
|
567
|
-
|
568
|
-
|
569
|
-
|
570
|
-
|
571
|
-
|
1184
|
+
require 'mysql2'
|
1185
|
+
require 'ddtrace'
|
1186
|
+
|
1187
|
+
Datadog.configure do |c|
|
1188
|
+
c.use :mysql2, options
|
572
1189
|
end
|
1190
|
+
|
1191
|
+
client = Mysql2::Client.new(:host => "localhost", :username => "root")
|
1192
|
+
client.query("SELECT * FROM users WHERE group='x'")
|
573
1193
|
```
|
574
1194
|
|
575
|
-
|
1195
|
+
Where `options` is an optional `Hash` that accepts the following parameters:
|
1196
|
+
|
1197
|
+
| Key | Description | Default |
|
1198
|
+
| --- | ----------- | ------- |
|
1199
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `false` |
|
1200
|
+
| `service_name` | Service name used for `mysql2` instrumentation | `'mysql2'` |
|
1201
|
+
|
1202
|
+
### Net/HTTP
|
1203
|
+
|
1204
|
+
The Net/HTTP integration will trace any HTTP call using the standard lib Net::HTTP module.
|
576
1205
|
|
577
1206
|
```ruby
|
578
|
-
|
579
|
-
|
580
|
-
|
581
|
-
|
582
|
-
|
1207
|
+
require 'net/http'
|
1208
|
+
require 'ddtrace'
|
1209
|
+
|
1210
|
+
Datadog.configure do |c|
|
1211
|
+
c.use :http, options
|
1212
|
+
|
1213
|
+
# optionally, specify a different service name for hostnames matching a regex
|
1214
|
+
c.use :http, describes: /user-[^.]+\.example\.com/ do |http|
|
1215
|
+
http.service_name = 'user.example.com'
|
1216
|
+
http.split_by_domain = false # Only necessary if split_by_domain is true by default
|
1217
|
+
end
|
1218
|
+
end
|
1219
|
+
|
1220
|
+
Net::HTTP.start('127.0.0.1', 8080) do |http|
|
1221
|
+
request = Net::HTTP::Get.new '/index'
|
1222
|
+
response = http.request(request)
|
583
1223
|
end
|
1224
|
+
|
1225
|
+
content = Net::HTTP.get(URI('http://127.0.0.1/index.html'))
|
1226
|
+
```
|
1227
|
+
|
1228
|
+
Where `options` is an optional `Hash` that accepts the following parameters:
|
1229
|
+
|
1230
|
+
| Key | Description | Default |
|
1231
|
+
| --- | ----------- | ------- |
|
1232
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `false` |
|
1233
|
+
| `distributed_tracing` | Enables [distributed tracing](#distributed-tracing) | `true` |
|
1234
|
+
| `service_name` | Service name used for `http` instrumentation | `'net/http'` |
|
1235
|
+
| `split_by_domain` | Uses the request domain as the service name when set to `true`. | `false` |
|
1236
|
+
|
1237
|
+
If you wish to configure each connection object individually, you may use the `Datadog.configure` as it follows:
|
1238
|
+
|
1239
|
+
```ruby
|
1240
|
+
client = Net::HTTP.new(host, port)
|
1241
|
+
Datadog.configure(client, options)
|
584
1242
|
```
|
585
1243
|
|
586
|
-
|
587
|
-
|
588
|
-
### MongoDB
|
1244
|
+
### Presto
|
589
1245
|
|
590
|
-
The integration traces any
|
1246
|
+
The Presto integration traces any SQL command sent through `presto-client` gem.
|
591
1247
|
|
592
1248
|
```ruby
|
593
|
-
require '
|
1249
|
+
require 'presto-client'
|
594
1250
|
require 'ddtrace'
|
595
1251
|
|
596
1252
|
Datadog.configure do |c|
|
597
|
-
c.use :
|
1253
|
+
c.use :presto, options
|
598
1254
|
end
|
599
1255
|
|
600
|
-
|
601
|
-
|
602
|
-
|
603
|
-
|
1256
|
+
client = Presto::Client.new(
|
1257
|
+
server: "localhost:8880",
|
1258
|
+
ssl: {verify: false},
|
1259
|
+
catalog: "native",
|
1260
|
+
schema: "default",
|
1261
|
+
time_zone: "US/Pacific",
|
1262
|
+
language: "English",
|
1263
|
+
http_debug: true,
|
1264
|
+
)
|
604
1265
|
|
605
|
-
|
606
|
-
Datadog.configure(client, service_name: 'mongodb-primary')
|
1266
|
+
client.run("select * from system.nodes")
|
607
1267
|
```
|
608
1268
|
|
609
1269
|
Where `options` is an optional `Hash` that accepts the following parameters:
|
610
1270
|
|
611
1271
|
| Key | Description | Default |
|
612
|
-
| --- |
|
613
|
-
|
|
614
|
-
|
|
1272
|
+
| --- | ----------- | ------- |
|
1273
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `false` |
|
1274
|
+
| `service_name` | Service name used for `presto` instrumentation | `'presto'` |
|
615
1275
|
|
616
|
-
###
|
1276
|
+
### Qless
|
617
1277
|
|
618
|
-
The
|
1278
|
+
The Qless integration uses lifecycle hooks to trace job executions.
|
1279
|
+
|
1280
|
+
To add tracing to a Qless job:
|
619
1281
|
|
620
1282
|
```ruby
|
621
|
-
require 'net/http'
|
622
1283
|
require 'ddtrace'
|
623
1284
|
|
624
1285
|
Datadog.configure do |c|
|
625
|
-
c.use :
|
1286
|
+
c.use :qless, options
|
626
1287
|
end
|
627
|
-
|
628
|
-
Net::HTTP.start('127.0.0.1', 8080) do |http|
|
629
|
-
request = Net::HTTP::Get.new '/index'
|
630
|
-
response = http.request request
|
631
|
-
end
|
632
|
-
|
633
|
-
content = Net::HTTP.get(URI('http://127.0.0.1/index.html'))
|
634
1288
|
```
|
635
1289
|
|
636
1290
|
Where `options` is an optional `Hash` that accepts the following parameters:
|
637
1291
|
|
638
1292
|
| Key | Description | Default |
|
639
|
-
| --- |
|
640
|
-
|
|
641
|
-
|
|
642
|
-
|
|
1293
|
+
| --- | ----------- | ------- |
|
1294
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to the global setting, `false` for off. | `false` |
|
1295
|
+
| `service_name` | Service name used for `qless` instrumentation | `'qless'` |
|
1296
|
+
| `tag_job_data` | Enable tagging with job arguments. true for on, false for off. | `false` |
|
1297
|
+
| `tag_job_tags` | Enable tagging with job tags. true for on, false for off. | `false` |
|
1298
|
+
|
1299
|
+
### Que
|
1300
|
+
|
1301
|
+
The Que integration is a middleware which will trace job executions.
|
643
1302
|
|
644
|
-
|
1303
|
+
You can enable it through `Datadog.configure`:
|
645
1304
|
|
646
1305
|
```ruby
|
647
|
-
|
648
|
-
|
1306
|
+
require 'ddtrace'
|
1307
|
+
|
1308
|
+
Datadog.configure do |c|
|
1309
|
+
c.use :que, options
|
1310
|
+
end
|
649
1311
|
```
|
650
1312
|
|
1313
|
+
Where `options` is an optional `Hash` that accepts the following parameters:
|
1314
|
+
|
1315
|
+
| Key | Description | Default |
|
1316
|
+
| --- | ----------- | ------- |
|
1317
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `false` |
|
1318
|
+
| `enabled` | Defines whether Que should be traced. Useful for temporarily disabling tracing. `true` or `false` | `true` |
|
1319
|
+
| `service_name` | Service name used for `que` instrumentation | `'que'` |
|
1320
|
+
| `tag_args` | Enable tagging of a job's args field. `true` for on, `false` for off. | `false` |
|
1321
|
+
| `tag_data` | Enable tagging of a job's data field. `true` for on, `false` for off. | `false` |
|
1322
|
+
| `error_handler` | Custom error handler invoked when a job raises an error. Provided `span` and `error` as arguments. Sets error on the span by default. Useful for ignoring transient errors. | `proc { |span, error| span.set_error(error) unless span.nil? }` |
|
1323
|
+
|
651
1324
|
### Racecar
|
652
1325
|
|
653
1326
|
The Racecar integration provides tracing for Racecar jobs.
|
@@ -665,15 +1338,15 @@ end
|
|
665
1338
|
Where `options` is an optional `Hash` that accepts the following parameters:
|
666
1339
|
|
667
1340
|
| Key | Description | Default |
|
668
|
-
| --- |
|
669
|
-
|
|
670
|
-
|
|
1341
|
+
| --- | ----------- | ------- |
|
1342
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `false` |
|
1343
|
+
| `service_name` | Service name used for `racecar` instrumentation | `'racecar'` |
|
671
1344
|
|
672
1345
|
### Rack
|
673
1346
|
|
674
1347
|
The Rack integration provides a middleware that traces all requests before they reach the underlying framework or application. It responds to the Rack minimal interface, providing reasonable values that can be retrieved at the Rack level.
|
675
1348
|
|
676
|
-
This integration is automatically activated with web frameworks like Rails. If you're using a plain Rack application,
|
1349
|
+
This integration is automatically activated with web frameworks like Rails. If you're using a plain Rack application, enable the integration it to your `config.ru`:
|
677
1350
|
|
678
1351
|
```ruby
|
679
1352
|
# config.ru example
|
@@ -695,20 +1368,20 @@ run app
|
|
695
1368
|
Where `options` is an optional `Hash` that accepts the following parameters:
|
696
1369
|
|
697
1370
|
| Key | Description | Default |
|
698
|
-
| --- |
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
1371
|
+
| --- | ----------- | ------- |
|
1372
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `nil` |
|
1373
|
+
| `application` | Your Rack application. Required for `middleware_names`. | `nil` |
|
1374
|
+
| `distributed_tracing` | Enables [distributed tracing](#distributed-tracing) so that this service trace is connected with a trace of another service if tracing headers are received | `true` |
|
1375
|
+
| `headers` | Hash of HTTP request or response headers to add as tags to the `rack.request`. Accepts `request` and `response` keys with Array values e.g. `['Last-Modified']`. Adds `http.request.headers.*` and `http.response.headers.*` tags respectively. | `{ response: ['Content-Type', 'X-Request-ID'] }` |
|
1376
|
+
| `middleware_names` | Enable this if you want to use the last executed middleware class as the resource name for the `rack` span. If enabled alongside the `rails` instrumention, `rails` takes precedence by setting the `rack` resource name to the active `rails` controller when applicable. Requires `application` option to use. | `false` |
|
1377
|
+
| `quantize` | Hash containing options for quantization. May include `:query` or `:fragment`. | `{}` |
|
1378
|
+
| `quantize.query` | Hash containing options for query portion of URL quantization. May include `:show` or `:exclude`. See options below. Option must be nested inside the `quantize` option. | `{}` |
|
1379
|
+
| `quantize.query.show` | Defines which values should always be shown. Shows no values by default. May be an Array of strings, or `:all` to show all values. Option must be nested inside the `query` option. | `nil` |
|
1380
|
+
| `quantize.query.exclude` | Defines which values should be removed entirely. Excludes nothing by default. May be an Array of strings, or `:all` to remove the query string entirely. Option must be nested inside the `query` option. | `nil` |
|
1381
|
+
| `quantize.fragment` | Defines behavior for URL fragments. Removes fragments by default. May be `:show` to show URL fragments. Option must be nested inside the `quantize` option. | `nil` |
|
1382
|
+
| `request_queuing` | Track HTTP request time spent in the queue of the frontend server. See [HTTP request queuing](#http-request-queuing) for setup details. Set to `true` to enable. | `false` |
|
1383
|
+
| `service_name` | Service name used for `rack` instrumentation | `'rack'` |
|
1384
|
+
| `web_service_name` | Service name for frontend server request queuing spans. (e.g. `'nginx'`) | `'web-server'` |
|
712
1385
|
|
713
1386
|
**Configuring URL quantization behavior**
|
714
1387
|
|
@@ -742,12 +1415,13 @@ end
|
|
742
1415
|
|
743
1416
|
### Rails
|
744
1417
|
|
745
|
-
The Rails integration will trace requests, database calls, templates rendering and cache read/write/delete operations. The integration makes use of the Active Support Instrumentation, listening to the Notification API so that any operation instrumented by the API is traced.
|
1418
|
+
The Rails integration will trace requests, database calls, templates rendering, and cache read/write/delete operations. The integration makes use of the Active Support Instrumentation, listening to the Notification API so that any operation instrumented by the API is traced.
|
746
1419
|
|
747
|
-
To enable the Rails
|
1420
|
+
To enable the Rails instrumentation, create an initializer file in your `config/initializers` folder:
|
748
1421
|
|
749
1422
|
```ruby
|
750
|
-
# config/initializers/datadog
|
1423
|
+
# config/initializers/datadog.rb
|
1424
|
+
require 'ddtrace'
|
751
1425
|
|
752
1426
|
Datadog.configure do |c|
|
753
1427
|
c.use :rails, options
|
@@ -757,16 +1431,30 @@ end
|
|
757
1431
|
Where `options` is an optional `Hash` that accepts the following parameters:
|
758
1432
|
|
759
1433
|
| Key | Description | Default |
|
760
|
-
| --- |
|
761
|
-
|
|
762
|
-
|
|
763
|
-
|
|
764
|
-
|
|
765
|
-
|
|
766
|
-
|
|
767
|
-
|
|
768
|
-
|
|
769
|
-
|
|
1434
|
+
| --- | ----------- | ------- |
|
1435
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to the global setting, `false` for off. | `nil` |
|
1436
|
+
| `cache_service` | Cache service name used when tracing cache activity | `'<app_name>-cache'` |
|
1437
|
+
| `controller_service` | Service name used when tracing a Rails action controller | `'<app_name>'` |
|
1438
|
+
| `database_service` | Database service name used when tracing database activity | `'<app_name>-<adapter_name>'` |
|
1439
|
+
| `distributed_tracing` | Enables [distributed tracing](#distributed-tracing) so that this service trace is connected with a trace of another service if tracing headers are received | `true` |
|
1440
|
+
| `exception_controller` | Class or Module which identifies a custom exception controller class. Tracer provides improved error behavior when it can identify custom exception controllers. By default, without this option, it 'guesses' what a custom exception controller looks like. Providing this option aids this identification. | `nil` |
|
1441
|
+
| `middleware` | Add the trace middleware to the Rails application. Set to `false` if you don't want the middleware to load. | `true` |
|
1442
|
+
| `middleware_names` | Enables any short-circuited middleware requests to display the middleware name as a resource for the trace. | `false` |
|
1443
|
+
| `service_name` | Service name used when tracing application requests (on the `rack` level) | `'<app_name>'` (inferred from your Rails application namespace) |
|
1444
|
+
| `template_base_path` | Used when the template name is parsed. If you don't store your templates in the `views/` folder, you may need to change this value | `'views/'` |
|
1445
|
+
| `log_injection` | Automatically enables injection [Trace Correlation](#trace-correlation) information, such as `dd.trace_id`, into Rails logs. Supports the default logger (`ActiveSupport::TaggedLogging`) and `Lograge`. Details on the format of Trace Correlation information can be found in the [Trace Correlation](#trace-correlation) section. | `false` |
|
1446
|
+
|
1447
|
+
**Supported versions**
|
1448
|
+
|
1449
|
+
| MRI Versions | JRuby Versions | Rails Versions |
|
1450
|
+
| ------------- | -------------- | -------------- |
|
1451
|
+
| 2.0 | | 3.0 - 3.2 |
|
1452
|
+
| 2.1 | | 3.0 - 4.2 |
|
1453
|
+
| 2.2 - 2.3 | | 3.0 - 5.2 |
|
1454
|
+
| 2.4 | | 4.2.8 - 5.2 |
|
1455
|
+
| 2.5 | | 4.2.8 - 6.1 |
|
1456
|
+
| 2.6 - 2.7 | 9.2 | 5.0 - 6.1 |
|
1457
|
+
| 3.0 | | 6.1 |
|
770
1458
|
|
771
1459
|
### Rake
|
772
1460
|
|
@@ -793,11 +1481,11 @@ Rake::Task['my_task'].invoke
|
|
793
1481
|
Where `options` is an optional `Hash` that accepts the following parameters:
|
794
1482
|
|
795
1483
|
| Key | Description | Default |
|
796
|
-
| --- |
|
797
|
-
|
|
798
|
-
|
|
799
|
-
|
|
800
|
-
|
|
1484
|
+
| --- | ----------- | ------- |
|
1485
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to the global setting, `false` for off. | `false` |
|
1486
|
+
| `enabled` | Defines whether Rake tasks should be traced. Useful for temporarily disabling tracing. `true` or `false` | `true` |
|
1487
|
+
| `quantize` | Hash containing options for quantization of task arguments. See below for more details and examples. | `{}` |
|
1488
|
+
| `service_name` | Service name used for `rake` instrumentation | `'rake'` |
|
801
1489
|
|
802
1490
|
**Configuring task quantization behavior**
|
803
1491
|
|
@@ -842,37 +1530,83 @@ require 'redis'
|
|
842
1530
|
require 'ddtrace'
|
843
1531
|
|
844
1532
|
Datadog.configure do |c|
|
845
|
-
c.use :redis,
|
1533
|
+
c.use :redis, options
|
846
1534
|
end
|
847
1535
|
|
848
|
-
#
|
1536
|
+
# Perform Redis commands
|
849
1537
|
redis = Redis.new
|
850
|
-
redis.set 'foo', 'bar'
|
1538
|
+
redis.set 'foo', 'bar'
|
851
1539
|
```
|
852
1540
|
|
853
1541
|
Where `options` is an optional `Hash` that accepts the following parameters:
|
854
1542
|
|
855
1543
|
| Key | Description | Default |
|
856
|
-
| --- |
|
857
|
-
|
|
1544
|
+
| --- | ----------- | ------- |
|
1545
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `false` |
|
1546
|
+
| `service_name` | Service name used for `redis` instrumentation | `'redis'` |
|
1547
|
+
| `command_args` | Show the command arguments (e.g. `key` in `GET key`) as resource name and tag | true |
|
858
1548
|
|
859
1549
|
You can also set *per-instance* configuration as it follows:
|
860
1550
|
|
861
1551
|
```ruby
|
1552
|
+
require 'redis'
|
1553
|
+
require 'ddtrace'
|
1554
|
+
|
1555
|
+
Datadog.configure do |c|
|
1556
|
+
c.use :redis # Enabling integration instrumentation is still required
|
1557
|
+
end
|
1558
|
+
|
862
1559
|
customer_cache = Redis.new
|
863
1560
|
invoice_cache = Redis.new
|
864
1561
|
|
865
1562
|
Datadog.configure(customer_cache, service_name: 'customer-cache')
|
866
|
-
Datadog.configure(invoice_cache, service_name: invoice-cache')
|
1563
|
+
Datadog.configure(invoice_cache, service_name: 'invoice-cache')
|
1564
|
+
|
1565
|
+
# Traced call will belong to `customer-cache` service
|
1566
|
+
customer_cache.get(...)
|
1567
|
+
# Traced call will belong to `invoice-cache` service
|
1568
|
+
invoice_cache.get(...)
|
1569
|
+
```
|
1570
|
+
|
1571
|
+
**Configuring trace settings per connection**
|
1572
|
+
|
1573
|
+
You can configure trace settings per connection by using the `describes` option:
|
1574
|
+
|
1575
|
+
```ruby
|
1576
|
+
# Provide a `:describes` option with a connection key.
|
1577
|
+
# Any of the following keys are acceptable and equivalent to one another.
|
1578
|
+
# If a block is provided, it yields a Settings object that
|
1579
|
+
# accepts any of the configuration options listed above.
|
867
1580
|
|
868
|
-
|
869
|
-
|
1581
|
+
Datadog.configure do |c|
|
1582
|
+
# The default configuration for any redis client
|
1583
|
+
c.use :redis, service_name: 'redis-default'
|
1584
|
+
|
1585
|
+
# The configuration matching a given unix socket.
|
1586
|
+
c.use :redis, describes: { url: 'unix://path/to/file' }, service_name: 'redis-unix'
|
1587
|
+
|
1588
|
+
# For network connections, only these fields are considered during matching:
|
1589
|
+
# scheme, host, port, db
|
1590
|
+
# Other fields are ignored.
|
1591
|
+
|
1592
|
+
# Network connection string
|
1593
|
+
c.use :redis, describes: 'redis://127.0.0.1:6379/0', service_name: 'redis-connection-string'
|
1594
|
+
c.use :redis, describes: { url: 'redis://127.0.0.1:6379/1' }, service_name: 'redis-connection-url'
|
1595
|
+
# Network client hash
|
1596
|
+
c.use :redis, describes: { host: 'my-host.com', port: 6379, db: 1, scheme: 'redis' }, service_name: 'redis-connection-hash'
|
1597
|
+
# Only a subset of the connection hash
|
1598
|
+
c.use :redis, describes: { host: ENV['APP_CACHE_HOST'], port: ENV['APP_CACHE_PORT'] }, service_name: 'redis-cache'
|
1599
|
+
c.use :redis, describes: { host: ENV['SIDEKIQ_CACHE_HOST'] }, service_name: 'redis-sidekiq'
|
1600
|
+
end
|
870
1601
|
```
|
871
1602
|
|
1603
|
+
When multiple `describes` configurations match a connection, the latest configured rule that matches will be applied.
|
1604
|
+
|
872
1605
|
### Resque
|
873
1606
|
|
874
|
-
The Resque integration uses Resque hooks that wraps the
|
875
|
-
|
1607
|
+
The Resque integration uses Resque hooks that wraps the `perform` method.
|
1608
|
+
|
1609
|
+
To add tracing to a Resque job:
|
876
1610
|
|
877
1611
|
```ruby
|
878
1612
|
require 'ddtrace'
|
@@ -891,9 +1625,56 @@ end
|
|
891
1625
|
Where `options` is an optional `Hash` that accepts the following parameters:
|
892
1626
|
|
893
1627
|
| Key | Description | Default |
|
894
|
-
| --- |
|
895
|
-
|
|
896
|
-
|
|
1628
|
+
| --- | ----------- | ------- |
|
1629
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to the global setting, `false` for off. | `false` |
|
1630
|
+
| `service_name` | Service name used for `resque` instrumentation | `'resque'` |
|
1631
|
+
| `workers` | An array including all worker classes you want to trace (e.g. `[MyJob]`) | `[]` |
|
1632
|
+
| `error_handler` | Custom error handler invoked when a job raises an error. Provided `span` and `error` as arguments. Sets error on the span by default. Useful for ignoring transient errors. | `proc { |span, error| span.set_error(error) unless span.nil? }` |
|
1633
|
+
|
1634
|
+
### Rest Client
|
1635
|
+
|
1636
|
+
The `rest-client` integration is available through the `ddtrace` middleware:
|
1637
|
+
|
1638
|
+
```ruby
|
1639
|
+
require 'rest_client'
|
1640
|
+
require 'ddtrace'
|
1641
|
+
|
1642
|
+
Datadog.configure do |c|
|
1643
|
+
c.use :rest_client, options
|
1644
|
+
end
|
1645
|
+
```
|
1646
|
+
|
1647
|
+
Where `options` is an optional `Hash` that accepts the following parameters:
|
1648
|
+
|
1649
|
+
| Key | Description | Default |
|
1650
|
+
| --- | ----------- | ------- |
|
1651
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `false` |
|
1652
|
+
| `distributed_tracing` | Enables [distributed tracing](#distributed-tracing) | `true` |
|
1653
|
+
| `service_name` | Service name for `rest_client` instrumentation. | `'rest_client'` |
|
1654
|
+
|
1655
|
+
### RSpec
|
1656
|
+
|
1657
|
+
RSpec integration will trace all executions of example groups and examples when using `rspec` test framework.
|
1658
|
+
|
1659
|
+
To activate your integration, use the `Datadog.configure` method:
|
1660
|
+
|
1661
|
+
```ruby
|
1662
|
+
require 'rspec'
|
1663
|
+
require 'ddtrace'
|
1664
|
+
|
1665
|
+
# Configure default RSpec integration
|
1666
|
+
Datadog.configure do |c|
|
1667
|
+
c.use :rspec, options
|
1668
|
+
end
|
1669
|
+
```
|
1670
|
+
|
1671
|
+
Where `options` is an optional `Hash` that accepts the following parameters:
|
1672
|
+
|
1673
|
+
| Key | Description | Default |
|
1674
|
+
| --- | ----------- | ------- |
|
1675
|
+
| `enabled` | Defines whether RSpec tests should be traced. Useful for temporarily disabling tracing. `true` or `false` | `true` |
|
1676
|
+
| `service_name` | Service name used for `rspec` instrumentation. | `'rspec'` |
|
1677
|
+
| `operation_name` | Operation name used for `rspec` instrumentation. Useful if you want rename automatic trace metrics e.g. `trace.#{operation_name}.errors`. | `'rspec.example'` |
|
897
1678
|
|
898
1679
|
### Sequel
|
899
1680
|
|
@@ -924,9 +1705,9 @@ articles.all
|
|
924
1705
|
Where `options` is an optional `Hash` that accepts the following parameters:
|
925
1706
|
|
926
1707
|
| Key | Description | Default |
|
927
|
-
| --- |
|
928
|
-
|
|
929
|
-
|
|
1708
|
+
| --- | ----------- | ------- |
|
1709
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `false` |
|
1710
|
+
| `service_name` | Service name for `sequel` instrumentation | Name of database adapter (e.g. `'mysql2'`) |
|
930
1711
|
|
931
1712
|
Only Ruby 2.0+ is supported.
|
932
1713
|
|
@@ -943,9 +1724,31 @@ Datadog.configure(sqlite_database, service_name: 'my-sqlite-db')
|
|
943
1724
|
Datadog.configure(postgres_database, service_name: 'my-postgres-db')
|
944
1725
|
```
|
945
1726
|
|
1727
|
+
### Shoryuken
|
1728
|
+
|
1729
|
+
The Shoryuken integration is a server-side middleware which will trace job executions.
|
1730
|
+
|
1731
|
+
You can enable it through `Datadog.configure`:
|
1732
|
+
|
1733
|
+
```ruby
|
1734
|
+
require 'ddtrace'
|
1735
|
+
|
1736
|
+
Datadog.configure do |c|
|
1737
|
+
c.use :shoryuken, options
|
1738
|
+
end
|
1739
|
+
```
|
1740
|
+
|
1741
|
+
Where `options` is an optional `Hash` that accepts the following parameters:
|
1742
|
+
|
1743
|
+
| Key | Description | Default |
|
1744
|
+
| --- | ----------- | ------- |
|
1745
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `false` |
|
1746
|
+
| `service_name` | Service name used for `shoryuken` instrumentation | `'shoryuken'` |
|
1747
|
+
| `error_handler` | Custom error handler invoked when a job raises an error. Provided `span` and `error` as arguments. Sets error on the span by default. Useful for ignoring transient errors. | `proc { |span, error| span.set_error(error) unless span.nil? }` |
|
1748
|
+
|
946
1749
|
### Sidekiq
|
947
1750
|
|
948
|
-
The Sidekiq integration is a server-side middleware which will trace job executions.
|
1751
|
+
The Sidekiq integration is a client-side & server-side middleware which will trace job queuing and executions respectively.
|
949
1752
|
|
950
1753
|
You can enable it through `Datadog.configure`:
|
951
1754
|
|
@@ -960,20 +1763,24 @@ end
|
|
960
1763
|
Where `options` is an optional `Hash` that accepts the following parameters:
|
961
1764
|
|
962
1765
|
| Key | Description | Default |
|
963
|
-
| --- |
|
964
|
-
|
|
1766
|
+
| --- | ----------- | ------- |
|
1767
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `false` |
|
1768
|
+
| `client_service_name` | Service name used for client-side `sidekiq` instrumentation | `'sidekiq-client'` |
|
1769
|
+
| `service_name` | Service name used for server-side `sidekiq` instrumentation | `'sidekiq'` |
|
1770
|
+
| `tag_args` | Enable tagging of job arguments. `true` for on, `false` for off. | `false` |
|
1771
|
+
| `error_handler` | Custom error handler invoked when a job raises an error. Provided `span` and `error` as arguments. Sets error on the span by default. Useful for ignoring transient errors. | `proc { |span, error| span.set_error(error) unless span.nil? }` |
|
965
1772
|
|
966
1773
|
### Sinatra
|
967
1774
|
|
968
1775
|
The Sinatra integration traces requests and template rendering.
|
969
1776
|
|
970
|
-
To start using the tracing client, make sure you import
|
971
|
-
|
1777
|
+
To start using the tracing client, make sure you import `ddtrace` and `use :sinatra` after either `sinatra` or `sinatra/base`, and before you define your application/routes:
|
1778
|
+
|
1779
|
+
#### Classic application
|
972
1780
|
|
973
1781
|
```ruby
|
974
1782
|
require 'sinatra'
|
975
1783
|
require 'ddtrace'
|
976
|
-
require 'ddtrace/contrib/sinatra/tracer'
|
977
1784
|
|
978
1785
|
Datadog.configure do |c|
|
979
1786
|
c.use :sinatra, options
|
@@ -984,15 +1791,72 @@ get '/' do
|
|
984
1791
|
end
|
985
1792
|
```
|
986
1793
|
|
1794
|
+
#### Modular application
|
1795
|
+
|
1796
|
+
```ruby
|
1797
|
+
require 'sinatra/base'
|
1798
|
+
require 'ddtrace'
|
1799
|
+
|
1800
|
+
Datadog.configure do |c|
|
1801
|
+
c.use :sinatra, options
|
1802
|
+
end
|
1803
|
+
|
1804
|
+
class NestedApp < Sinatra::Base
|
1805
|
+
register Datadog::Contrib::Sinatra::Tracer
|
1806
|
+
|
1807
|
+
get '/nested' do
|
1808
|
+
'Hello from nested app!'
|
1809
|
+
end
|
1810
|
+
end
|
1811
|
+
|
1812
|
+
class App < Sinatra::Base
|
1813
|
+
register Datadog::Contrib::Sinatra::Tracer
|
1814
|
+
|
1815
|
+
use NestedApp
|
1816
|
+
|
1817
|
+
get '/' do
|
1818
|
+
'Hello world!'
|
1819
|
+
end
|
1820
|
+
end
|
1821
|
+
```
|
1822
|
+
|
1823
|
+
Ensure you register `Datadog::Contrib::Sinatra::Tracer` as a middleware before you mount your nested applications.
|
1824
|
+
|
1825
|
+
#### Instrumentation options
|
1826
|
+
|
1827
|
+
`options` is an optional `Hash` that accepts the following parameters:
|
1828
|
+
|
1829
|
+
| Key | Description | Default |
|
1830
|
+
| --- | ----------- | ------- |
|
1831
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `nil` |
|
1832
|
+
| `distributed_tracing` | Enables [distributed tracing](#distributed-tracing) so that this service trace is connected with a trace of another service if tracing headers are received | `true` |
|
1833
|
+
| `headers` | Hash of HTTP request or response headers to add as tags to the `sinatra.request`. Accepts `request` and `response` keys with Array values e.g. `['Last-Modified']`. Adds `http.request.headers.*` and `http.response.headers.*` tags respectively. | `{ response: ['Content-Type', 'X-Request-ID'] }` |
|
1834
|
+
| `resource_script_names` | Prepend resource names with script name | `false` |
|
1835
|
+
| `service_name` | Service name used for `sinatra` instrumentation | `'sinatra'` |
|
1836
|
+
|
1837
|
+
### Sneakers
|
1838
|
+
|
1839
|
+
The Sneakers integration is a server-side middleware which will trace job executions.
|
1840
|
+
|
1841
|
+
You can enable it through `Datadog.configure`:
|
1842
|
+
|
1843
|
+
```ruby
|
1844
|
+
require 'ddtrace'
|
1845
|
+
|
1846
|
+
Datadog.configure do |c|
|
1847
|
+
c.use :sneakers, options
|
1848
|
+
end
|
1849
|
+
```
|
1850
|
+
|
987
1851
|
Where `options` is an optional `Hash` that accepts the following parameters:
|
988
1852
|
|
989
1853
|
| Key | Description | Default |
|
990
|
-
| --- |
|
991
|
-
|
|
992
|
-
|
|
993
|
-
|
|
994
|
-
|
|
995
|
-
|
|
1854
|
+
| --- | ----------- | ------- |
|
1855
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `false` |
|
1856
|
+
| `enabled` | Defines whether Sneakers should be traced. Useful for temporarily disabling tracing. `true` or `false` | `true` |
|
1857
|
+
| `service_name` | Service name used for `sneakers` instrumentation | `'sneakers'` |
|
1858
|
+
| `tag_body` | Enable tagging of job message. `true` for on, `false` for off. | `false` |
|
1859
|
+
| `error_handler` | Custom error handler invoked when a job raises an error. Provided `span` and `error` as arguments. Sets error on the span by default. Useful for ignoring transient errors. | `proc { |span, error| span.set_error(error) unless span.nil? }` |
|
996
1860
|
|
997
1861
|
### Sucker Punch
|
998
1862
|
|
@@ -1005,15 +1869,16 @@ Datadog.configure do |c|
|
|
1005
1869
|
c.use :sucker_punch, options
|
1006
1870
|
end
|
1007
1871
|
|
1008
|
-
#
|
1872
|
+
# Execution of this job is traced
|
1009
1873
|
LogJob.perform_async('login')
|
1010
1874
|
```
|
1011
1875
|
|
1012
1876
|
Where `options` is an optional `Hash` that accepts the following parameters:
|
1013
1877
|
|
1014
1878
|
| Key | Description | Default |
|
1015
|
-
| --- |
|
1016
|
-
|
|
1879
|
+
| --- | ----------- | ------- |
|
1880
|
+
| `analytics_enabled` | Enable analytics for spans produced by this integration. `true` for on, `nil` to defer to global setting, `false` for off. | `false` |
|
1881
|
+
| `service_name` | Service name used for `sucker_punch` instrumentation | `'sucker_punch'` |
|
1017
1882
|
|
1018
1883
|
## Advanced configuration
|
1019
1884
|
|
@@ -1025,98 +1890,127 @@ To change the default behavior of the Datadog tracer, you can provide custom opt
|
|
1025
1890
|
# config/initializers/datadog-tracer.rb
|
1026
1891
|
|
1027
1892
|
Datadog.configure do |c|
|
1028
|
-
c.tracer
|
1893
|
+
c.tracer.enabled = true
|
1894
|
+
c.tracer.hostname = 'my-agent'
|
1895
|
+
c.tracer.port = 8126
|
1896
|
+
c.tracer.partial_flush.enabled = false
|
1897
|
+
c.tracer.sampler = Datadog::AllSampler.new
|
1898
|
+
|
1899
|
+
# OR for advanced use cases, you can specify your own tracer:
|
1900
|
+
c.tracer.instance = Datadog::Tracer.new
|
1901
|
+
|
1902
|
+
# To enable debug mode:
|
1903
|
+
c.diagnostics.debug = true
|
1029
1904
|
end
|
1030
1905
|
```
|
1031
1906
|
|
1032
1907
|
Available options are:
|
1033
1908
|
|
1034
|
-
-
|
1035
|
-
|
1036
|
-
-
|
1037
|
-
-
|
1038
|
-
-
|
1039
|
-
-
|
1040
|
-
-
|
1041
|
-
-
|
1042
|
-
-
|
1909
|
+
- `enabled`: defines if the `tracer` is enabled or not. If set to `false` instrumentation will still run, but no spans are sent to the trace agent. Can be configured through the `DD_TRACE_ENABLED` environment variable. Defaults to `true`.
|
1910
|
+
- `hostname`: set the hostname of the trace agent.
|
1911
|
+
- `instance`: set to a custom `Datadog::Tracer` instance. If provided, other trace settings are ignored (you must configure it manually.)
|
1912
|
+
- `partial_flush.enabled`: set to `true` to enable partial trace flushing (for long running traces.) Disabled by default. *Experimental.*
|
1913
|
+
- `port`: set the port the trace agent is listening on.
|
1914
|
+
- `sampler`: set to a custom `Datadog::Sampler` instance. If provided, the tracer will use this sampler to determine sampling behavior.
|
1915
|
+
- `diagnostics.startup_logs.enabled`: Startup configuration and diagnostic log. Defaults to `true`. Can be configured through the `DD_TRACE_STARTUP_LOGS` environment variable.
|
1916
|
+
- `diagnostics.debug`: set to true to enable debug logging. Can be configured through the `DD_TRACE_DEBUG` environment variable. Defaults to `false`.
|
1917
|
+
- `time_now_provider`: when testing, it might be helpful to use a different time provider. For Timecop, for example, `->{ Time.now_without_mock_time }` allows the tracer to use the real wall time. Span duration calculation will still use the system monotonic clock when available, thus not being affected by this setting. Defaults to `->{ Time.now }`.
|
1043
1918
|
|
1044
1919
|
#### Custom logging
|
1045
1920
|
|
1046
1921
|
By default, all logs are processed by the default Ruby logger. When using Rails, you should see the messages in your application log file.
|
1047
1922
|
|
1048
|
-
Datadog client log messages are marked with
|
1923
|
+
Datadog client log messages are marked with `[ddtrace]` so you should be able to isolate them from other messages.
|
1049
1924
|
|
1050
|
-
Additionally, it is possible to override the default logger and replace it by a custom one. This is done using the
|
1925
|
+
Additionally, it is possible to override the default logger and replace it by a custom one. This is done using the `log` setting.
|
1051
1926
|
|
1052
1927
|
```ruby
|
1053
|
-
f = File.new("my-custom.log", "w+")
|
1928
|
+
f = File.new("my-custom.log", "w+") # Log messages should go there
|
1054
1929
|
Datadog.configure do |c|
|
1055
|
-
c.
|
1930
|
+
c.logger = Logger.new(f) # Overriding the default logger
|
1931
|
+
c.logger.level = ::Logger::INFO
|
1056
1932
|
end
|
1057
1933
|
|
1058
|
-
Datadog
|
1934
|
+
Datadog.logger.info { "this is typically called by tracing code" }
|
1059
1935
|
```
|
1060
1936
|
|
1061
1937
|
### Environment and tags
|
1062
1938
|
|
1063
1939
|
By default, the trace agent (not this library, but the program running in the background collecting data from various clients) uses the tags set in the agent config file, see our [environments tutorial](https://app.datadoghq.com/apm/docs/tutorials/environments) for details.
|
1064
1940
|
|
1065
|
-
|
1941
|
+
You can configure the application to automatically tag your traces and metrics, using the following environment variables:
|
1942
|
+
|
1943
|
+
- `DD_ENV`: Your application environment (e.g. `production`, `staging`, etc.)
|
1944
|
+
- `DD_SERVICE`: Your application's default service name (e.g. `billing-api`)
|
1945
|
+
- `DD_VERSION`: Your application version (e.g. `2.5`, `202003181415`, `1.3-alpha`, etc.)
|
1946
|
+
- `DD_TAGS`: Custom tags in value pairs separated by `,` (e.g. `layer:api,team:intake`)
|
1947
|
+
- If `DD_ENV`, `DD_SERVICE` or `DD_VERSION` are set, it will override any respective `env`/`service`/`version` tag defined in `DD_TAGS`.
|
1948
|
+
- If `DD_ENV`, `DD_SERVICE` or `DD_VERSION` are NOT set, tags defined in `DD_TAGS` will be used to populate `env`/`service`/`version` respectively.
|
1949
|
+
|
1950
|
+
These values can also be overridden at the tracer level:
|
1066
1951
|
|
1067
1952
|
```ruby
|
1068
1953
|
Datadog.configure do |c|
|
1069
|
-
c.
|
1954
|
+
c.service = 'billing-api'
|
1955
|
+
c.env = 'test'
|
1956
|
+
c.tags = { 'team' => 'qa' }
|
1957
|
+
c.version = '1.3-alpha'
|
1070
1958
|
end
|
1071
1959
|
```
|
1072
1960
|
|
1073
|
-
This enables you to set this value on a per
|
1961
|
+
This enables you to set this value on a per application basis, so you can have for example several applications reporting for different environments on the same host.
|
1962
|
+
|
1963
|
+
Tags can also be set directly on individual spans, which will supersede any conflicting tags defined at the application level.
|
1074
1964
|
|
1075
|
-
|
1965
|
+
### Environment variables
|
1966
|
+
|
1967
|
+
Other Environment Variables:
|
1968
|
+
|
1969
|
+
- `DD_TRACE_AGENT_URL`: Sets the URL endpoint where traces are sent. Has priority over `DD_AGENT_HOST` and `DD_TRACE_AGENT_PORT` if set. e.g. `DD_TRACE_AGENT_URL=http://localhost:8126`.
|
1970
|
+
- `DD_TRACE_<INTEGRATION>_ENABLED`: Enables or disables an **activated** integration. Defaults to `true`.. e.g. `DD_TRACE_RAILS_ENABLED=false`. This option has no effects on integrations that have not been explicitly activated (e.g. `Datadog.configure{ |c| c.use :integration }`).on code. This environment variable can only be used to disable an integration.
|
1971
|
+
- `DD_TRACE_<INTEGRATION>_ANALYTICS_ENABLED`: Enables or disable App Analytics for a specific integration. Valid values are: true or false (default). e.g. `DD_TRACE_ACTION_CABLE_ANALYTICS_ENABLED=true`.
|
1972
|
+
- `DD_TRACE_<INTEGRATION>_ANALYTICS_SAMPLE_RATE`: Sets the App Analytics sampling rate for a specific integration. A floating number between 0.0 and 1.0 (default). e.g. `DD_TRACE_ACTION_CABLE_ANALYTICS_SAMPLE_RATE=0.5`.
|
1973
|
+
- `DD_LOGS_INJECTION`: Automatically enables injection [Trace Correlation](#trace-correlation) information, such as `dd.trace_id`, into Rails logs. Supports the default logger (`ActiveSupport::TaggedLogging`) and `Lograge`. Details on the format of Trace Correlation information can be found in the [Trace Correlation](#trace-correlation) section. Valid values are: `true` or `false`(default). e.g. `DD_LOGS_INJECTION=true`.
|
1076
1974
|
|
1077
1975
|
### Sampling
|
1078
1976
|
|
1079
|
-
`ddtrace` can perform trace sampling. While the trace agent already samples traces to reduce bandwidth usage, client sampling reduces performance overhead.
|
1977
|
+
`ddtrace` can perform trace sampling. While the trace agent already samples traces to reduce bandwidth usage, client sampling reduces the performance overhead.
|
1080
1978
|
|
1081
1979
|
`Datadog::RateSampler` samples a ratio of the traces. For example:
|
1082
1980
|
|
1083
1981
|
```ruby
|
1084
1982
|
# Sample rate is between 0 (nothing sampled) to 1 (everything sampled).
|
1085
1983
|
sampler = Datadog::RateSampler.new(0.5) # sample 50% of the traces
|
1984
|
+
|
1086
1985
|
Datadog.configure do |c|
|
1087
|
-
c.tracer
|
1986
|
+
c.tracer.sampler = sampler
|
1088
1987
|
end
|
1089
1988
|
```
|
1090
1989
|
|
1091
1990
|
#### Priority sampling
|
1092
1991
|
|
1093
|
-
Priority sampling
|
1992
|
+
Priority sampling decides whether to keep a trace by using a priority attribute propagated for distributed traces. Its value indicates to the Agent and the backend about how important the trace is.
|
1094
1993
|
|
1095
1994
|
The sampler can set the priority to the following values:
|
1096
1995
|
|
1097
1996
|
- `Datadog::Ext::Priority::AUTO_REJECT`: the sampler automatically decided to reject the trace.
|
1098
1997
|
- `Datadog::Ext::Priority::AUTO_KEEP`: the sampler automatically decided to keep the trace.
|
1099
1998
|
|
1100
|
-
|
1101
|
-
|
1102
|
-
```ruby
|
1103
|
-
Datadog.configure do |c|
|
1104
|
-
c.tracer priority_sampling: true
|
1105
|
-
end
|
1106
|
-
```
|
1107
|
-
|
1108
|
-
Once enabled, the sampler will automatically assign a priority of 0 or 1 to traces, depending on their service and volume.
|
1999
|
+
Priority sampling is enabled by default. Enabling it ensures that your sampled distributed traces will be complete. Once enabled, the sampler will automatically assign a priority of 0 or 1 to traces, depending on their service and volume.
|
1109
2000
|
|
1110
2001
|
You can also set this priority manually to either drop a non-interesting trace or to keep an important one. For that, set the `context#sampling_priority` to:
|
1111
2002
|
|
1112
2003
|
- `Datadog::Ext::Priority::USER_REJECT`: the user asked to reject the trace.
|
1113
2004
|
- `Datadog::Ext::Priority::USER_KEEP`: the user asked to keep the trace.
|
1114
2005
|
|
1115
|
-
When not using [distributed tracing](#distributed-tracing), you may change the priority at any time, as long as the trace
|
2006
|
+
When not using [distributed tracing](#distributed-tracing), you may change the priority at any time, as long as the trace incomplete. But it has to be done before any context propagation (fork, RPC calls) to be useful in a distributed context. Changing the priority after the context has been propagated causes different parts of a distributed trace to use different priorities. Some parts might be kept, some parts might be rejected, and this can cause the trace to be partially stored and remain incomplete.
|
1116
2007
|
|
1117
|
-
If you change the priority, we recommend you do it as soon as possible
|
2008
|
+
If you change the priority, we recommend you do it as soon as possible - when the root span has just been created.
|
1118
2009
|
|
1119
2010
|
```ruby
|
2011
|
+
# First, grab the active span
|
2012
|
+
span = Datadog.tracer.active_span
|
2013
|
+
|
1120
2014
|
# Indicate to reject the trace
|
1121
2015
|
span.context.sampling_priority = Datadog::Ext::Priority::USER_REJECT
|
1122
2016
|
|
@@ -1126,7 +2020,7 @@ span.context.sampling_priority = Datadog::Ext::Priority::USER_KEEP
|
|
1126
2020
|
|
1127
2021
|
### Distributed Tracing
|
1128
2022
|
|
1129
|
-
Distributed tracing allows traces to be propagated across multiple instrumented applications
|
2023
|
+
Distributed tracing allows traces to be propagated across multiple instrumented applications so that a request can be presented as a single trace, rather than a separate trace per service.
|
1130
2024
|
|
1131
2025
|
To trace requests across application boundaries, the following must be propagated between each application:
|
1132
2026
|
|
@@ -1211,7 +2105,7 @@ Service B:
|
|
1211
2105
|
Priority: 1
|
1212
2106
|
|
1213
2107
|
|
|
1214
|
-
| Service
|
2108
|
+
| Service C HTTP Request:
|
1215
2109
|
| Headers:
|
1216
2110
|
| x-datadog-trace-id: 100000000000000001
|
1217
2111
|
| x-datadog-parent-id: 100000000000000456
|
@@ -1228,20 +2122,24 @@ Service C:
|
|
1228
2122
|
|
1229
2123
|
**Activating distributed tracing for integrations**
|
1230
2124
|
|
1231
|
-
Many integrations included in `ddtrace` support distributed tracing. Distributed tracing is
|
2125
|
+
Many integrations included in `ddtrace` support distributed tracing. Distributed tracing is enabled by default in Agent v7 and most versions of Agent v6. If needed, you can activate distributed tracing with configuration settings.
|
1232
2126
|
|
1233
2127
|
- If your application receives requests from services with distributed tracing activated, you must activate distributed tracing on the integrations that handle these requests (e.g. Rails)
|
1234
2128
|
- If your application send requests to services with distributed tracing activated, you must activate distributed tracing on the integrations that send these requests (e.g. Faraday)
|
1235
|
-
- If your application both sends and receives requests implementing distributed tracing, it must activate all integrations
|
2129
|
+
- If your application both sends and receives requests implementing distributed tracing, it must activate all integrations that handle these requests.
|
1236
2130
|
|
1237
2131
|
For more details on how to activate distributed tracing for integrations, see their documentation:
|
1238
2132
|
|
1239
2133
|
- [Excon](#excon)
|
1240
2134
|
- [Faraday](#faraday)
|
2135
|
+
- [Rest Client](#restclient)
|
1241
2136
|
- [Net/HTTP](#nethttp)
|
1242
2137
|
- [Rack](#rack)
|
1243
2138
|
- [Rails](#rails)
|
1244
2139
|
- [Sinatra](#sinatra)
|
2140
|
+
- [http.rb](#http-rb)
|
2141
|
+
- [httpclient](#httpclient)
|
2142
|
+
- [httpx](#httpx)
|
1245
2143
|
|
1246
2144
|
**Using the HTTP propagator**
|
1247
2145
|
|
@@ -1268,11 +2166,9 @@ end
|
|
1268
2166
|
|
1269
2167
|
### HTTP request queuing
|
1270
2168
|
|
1271
|
-
Traces that originate from HTTP requests can be configured to include the time spent in a frontend web server or load balancer queue
|
1272
|
-
|
1273
|
-
This functionality is **experimental** and deactivated by default.
|
2169
|
+
Traces that originate from HTTP requests can be configured to include the time spent in a frontend web server or load balancer queue before the request reaches the Ruby application.
|
1274
2170
|
|
1275
|
-
To activate
|
2171
|
+
This feature is disabled by default. To activate it, you must add an `X-Request-Start` or `X-Queue-Start` header from your web server (i.e., Nginx). The following is an Nginx configuration example:
|
1276
2172
|
|
1277
2173
|
```
|
1278
2174
|
# /etc/nginx/conf.d/ruby_service.conf
|
@@ -1286,9 +2182,7 @@ server {
|
|
1286
2182
|
}
|
1287
2183
|
```
|
1288
2184
|
|
1289
|
-
Then you must enable the request queuing feature in the integration handling the request.
|
1290
|
-
|
1291
|
-
For Rack based applications, see the [documentation](#rack) for details for enabling this feature.
|
2185
|
+
Then you must enable the request queuing feature, by setting `request_queuing: true`, in the integration handling the request. For Rack-based applications, see the [documentation](#rack) for details.
|
1292
2186
|
|
1293
2187
|
### Processing Pipeline
|
1294
2188
|
|
@@ -1352,3 +2246,254 @@ Datadog::Pipeline.before_flush(
|
|
1352
2246
|
Datadog::Pipeline::SpanProcessor.new { |span| span.resource.gsub!(/password=.*/, '') }
|
1353
2247
|
)
|
1354
2248
|
```
|
2249
|
+
|
2250
|
+
### Trace correlation
|
2251
|
+
|
2252
|
+
In many cases, such as logging, it may be useful to correlate trace IDs to other events or data streams, for easier cross-referencing.
|
2253
|
+
|
2254
|
+
#### For logging in Rails applications
|
2255
|
+
|
2256
|
+
##### Automatic
|
2257
|
+
|
2258
|
+
For Rails applications using the default logger (`ActiveSupport::TaggedLogging`) or `lograge`, you can automatically enable trace correlation injection by setting the `rails` instrumentation configuration option `log_injection` to `true` or by setting environment variable `DD_LOGS_INJECTION=true`:
|
2259
|
+
|
2260
|
+
```ruby
|
2261
|
+
# config/initializers/datadog.rb
|
2262
|
+
require 'ddtrace'
|
2263
|
+
|
2264
|
+
Datadog.configure do |c|
|
2265
|
+
c.use :rails, log_injection: true
|
2266
|
+
end
|
2267
|
+
```
|
2268
|
+
|
2269
|
+
_Note:_ For `lograge` users who have also defined `lograge.custom_options` in an `initializers/lograge.rb` configuration file, due to the order that Rails loads initializers (alphabetical), automatic trace correlation may not take effect, since `initializers/datadog.rb` would be overwritten by the `initializers/lograge.rb` initializer. To support automatic trace correlation with _existing_ `lograge.custom_options`, use the [Manual (Lograge)](#manual-lograge) configuration below.
|
2270
|
+
|
2271
|
+
##### Manual (Lograge)
|
2272
|
+
|
2273
|
+
After [setting up Lograge in a Rails application](https://docs.datadoghq.com/logs/log_collection/ruby/), manually modify the `custom_options` block in your environment configuration file (e.g. `config/environments/production.rb`) to add the trace IDs.
|
2274
|
+
|
2275
|
+
```ruby
|
2276
|
+
config.lograge.custom_options = lambda do |event|
|
2277
|
+
# Retrieves trace information for current thread
|
2278
|
+
correlation = Datadog.tracer.active_correlation
|
2279
|
+
|
2280
|
+
{
|
2281
|
+
# Adds IDs as tags to log output
|
2282
|
+
:dd => {
|
2283
|
+
# To preserve precision during JSON serialization, use strings for large numbers
|
2284
|
+
:trace_id => correlation.trace_id.to_s,
|
2285
|
+
:span_id => correlation.span_id.to_s,
|
2286
|
+
:env => correlation.env.to_s,
|
2287
|
+
:service => correlation.service.to_s,
|
2288
|
+
:version => correlation.version.to_s
|
2289
|
+
},
|
2290
|
+
:ddsource => ["ruby"],
|
2291
|
+
:params => event.payload[:params].reject { |k| %w(controller action).include? k }
|
2292
|
+
}
|
2293
|
+
end
|
2294
|
+
```
|
2295
|
+
|
2296
|
+
##### Manual (ActiveSupport::TaggedLogging)
|
2297
|
+
|
2298
|
+
Rails applications which are configured with the default `ActiveSupport::TaggedLogging` logger can append correlation IDs as tags to log output. To enable Trace Correlation with `ActiveSupport::TaggedLogging`, in your Rails environment configuration file, add the following:
|
2299
|
+
|
2300
|
+
```ruby
|
2301
|
+
Rails.application.configure do
|
2302
|
+
config.log_tags = [proc { Datadog.tracer.active_correlation.to_s }]
|
2303
|
+
end
|
2304
|
+
|
2305
|
+
# Given:
|
2306
|
+
# DD_ENV = 'production' (The name of the environment your application is running in.)
|
2307
|
+
# DD_SERVICE = 'billing-api' (Default service name of your application.)
|
2308
|
+
# DD_VERSION = '2.5.17' (The version of your application.)
|
2309
|
+
|
2310
|
+
# Web requests will produce:
|
2311
|
+
# [dd.env=production dd.service=billing-api dd.version=2.5.17 dd.trace_id=7110975754844687674 dd.span_id=7518426836986654206] Started GET "/articles" for 172.22.0.1 at 2019-01-16 18:50:57 +0000
|
2312
|
+
# [dd.env=production dd.service=billing-api dd.version=2.5.17 dd.trace_id=7110975754844687674 dd.span_id=7518426836986654206] Processing by ArticlesController#index as */*
|
2313
|
+
# [dd.env=production dd.service=billing-api dd.version=2.5.17 dd.trace_id=7110975754844687674 dd.span_id=7518426836986654206] Article Load (0.5ms) SELECT "articles".* FROM "articles"
|
2314
|
+
# [dd.env=production dd.service=billing-api dd.version=2.5.17 dd.trace_id=7110975754844687674 dd.span_id=7518426836986654206] Completed 200 OK in 7ms (Views: 5.5ms | ActiveRecord: 0.5ms)
|
2315
|
+
```
|
2316
|
+
|
2317
|
+
#### For logging in Ruby applications
|
2318
|
+
|
2319
|
+
To add correlation IDs to your logger, add a log formatter which retrieves the correlation IDs with `Datadog.tracer.active_correlation`, then add them to the message.
|
2320
|
+
|
2321
|
+
To properly correlate with Datadog logging, be sure the following is present in the log message, in order as they appear:
|
2322
|
+
|
2323
|
+
- `dd.env=<ENV>`: Where `<ENV>` is equal to `Datadog.tracer.active_correlation.env`. Omit if no environment is configured.
|
2324
|
+
- `dd.service=<SERVICE>`: Where `<SERVICE>` is equal to `Datadog.tracer.active_correlation.service`. Omit if no default service name is configured.
|
2325
|
+
- `dd.version=<VERSION>`: Where `<VERSION>` is equal to `Datadog.tracer.active_correlation.version`. Omit if no application version is configured.
|
2326
|
+
- `dd.trace_id=<TRACE_ID>`: Where `<TRACE_ID>` is equal to `Datadog.tracer.active_correlation.trace_id` or `0` if no trace is active during logging.
|
2327
|
+
- `dd.span_id=<SPAN_ID>`: Where `<SPAN_ID>` is equal to `Datadog.tracer.active_correlation.span_id` or `0` if no trace is active during logging.
|
2328
|
+
|
2329
|
+
By default, `Datadog::Correlation::Identifier#to_s` will return `dd.env=<ENV> dd.service=<SERVICE> dd.version=<VERSION> dd.trace_id=<TRACE_ID> dd.span_id=<SPAN_ID>`.
|
2330
|
+
|
2331
|
+
If a trace is not active and the application environment & version is not configured, it will return `dd.trace_id=0 dd.span_id=0 dd.env= dd.version=`.
|
2332
|
+
|
2333
|
+
An example of this in practice:
|
2334
|
+
|
2335
|
+
```ruby
|
2336
|
+
require 'ddtrace'
|
2337
|
+
require 'logger'
|
2338
|
+
|
2339
|
+
ENV['DD_ENV'] = 'production'
|
2340
|
+
ENV['DD_SERVICE'] = 'billing-api'
|
2341
|
+
ENV['DD_VERSION'] = '2.5.17'
|
2342
|
+
|
2343
|
+
logger = Logger.new(STDOUT)
|
2344
|
+
logger.progname = 'my_app'
|
2345
|
+
logger.formatter = proc do |severity, datetime, progname, msg|
|
2346
|
+
"[#{datetime}][#{progname}][#{severity}][#{Datadog.tracer.active_correlation}] #{msg}\n"
|
2347
|
+
end
|
2348
|
+
|
2349
|
+
# When no trace is active
|
2350
|
+
logger.warn('This is an untraced operation.')
|
2351
|
+
# [2019-01-16 18:38:41 +0000][my_app][WARN][dd.env=production dd.service=billing-api dd.version=2.5.17 dd.trace_id=0 dd.span_id=0] This is an untraced operation.
|
2352
|
+
|
2353
|
+
# When a trace is active
|
2354
|
+
Datadog.tracer.trace('my.operation') { logger.warn('This is a traced operation.') }
|
2355
|
+
# [2019-01-16 18:38:41 +0000][my_app][WARN][dd.env=production dd.service=billing-api dd.version=2.5.17 dd.trace_id=8545847825299552251 dd.span_id=3711755234730770098] This is a traced operation.
|
2356
|
+
```
|
2357
|
+
|
2358
|
+
### Configuring the transport layer
|
2359
|
+
|
2360
|
+
By default, the tracer submits trace data using `Net::HTTP` to `127.0.0.1:8126`, the default location for the Datadog trace agent process. However, the tracer can be configured to send its trace data to alternative destinations, or by alternative protocols.
|
2361
|
+
|
2362
|
+
Some basic settings, such as hostname and port, can be configured using [tracer settings](#tracer-settings).
|
2363
|
+
|
2364
|
+
#### Using the Net::HTTP adapter
|
2365
|
+
|
2366
|
+
The `Net` adapter submits traces using `Net::HTTP` over TCP. It is the default transport adapter.
|
2367
|
+
|
2368
|
+
```ruby
|
2369
|
+
Datadog.configure do |c|
|
2370
|
+
c.tracer.transport_options = proc { |t|
|
2371
|
+
# Hostname, port, and additional options. :timeout is in seconds.
|
2372
|
+
t.adapter :net_http, '127.0.0.1', 8126, { timeout: 1 }
|
2373
|
+
}
|
2374
|
+
end
|
2375
|
+
```
|
2376
|
+
|
2377
|
+
#### Using the Unix socket adapter
|
2378
|
+
|
2379
|
+
The `UnixSocket` adapter submits traces using `Net::HTTP` over Unix socket.
|
2380
|
+
|
2381
|
+
To use, first configure your trace agent to listen by Unix socket, then configure the tracer with:
|
2382
|
+
|
2383
|
+
```ruby
|
2384
|
+
Datadog.configure do |c|
|
2385
|
+
c.tracer.transport_options = proc { |t|
|
2386
|
+
# Provide filepath to trace agent Unix socket
|
2387
|
+
t.adapter :unix, '/tmp/ddagent/trace.sock'
|
2388
|
+
}
|
2389
|
+
end
|
2390
|
+
```
|
2391
|
+
|
2392
|
+
#### Using the transport test adapter
|
2393
|
+
|
2394
|
+
The `Test` adapter is a no-op transport that can optionally buffer requests. For use in test suites or other non-production environments.
|
2395
|
+
|
2396
|
+
```ruby
|
2397
|
+
Datadog.configure do |c|
|
2398
|
+
c.tracer.transport_options = proc { |t|
|
2399
|
+
# Set transport to no-op mode. Does not retain traces.
|
2400
|
+
t.adapter :test
|
2401
|
+
|
2402
|
+
# Alternatively, you can provide a buffer to examine trace output.
|
2403
|
+
# The buffer must respond to '<<'.
|
2404
|
+
t.adapter :test, []
|
2405
|
+
}
|
2406
|
+
end
|
2407
|
+
```
|
2408
|
+
|
2409
|
+
#### Using a custom transport adapter
|
2410
|
+
|
2411
|
+
Custom adapters can be configured with:
|
2412
|
+
|
2413
|
+
```ruby
|
2414
|
+
Datadog.configure do |c|
|
2415
|
+
c.tracer.transport_options = proc { |t|
|
2416
|
+
# Initialize and pass an instance of the adapter
|
2417
|
+
custom_adapter = CustomAdapter.new
|
2418
|
+
t.adapter custom_adapter
|
2419
|
+
}
|
2420
|
+
end
|
2421
|
+
```
|
2422
|
+
|
2423
|
+
### Metrics
|
2424
|
+
|
2425
|
+
The tracer and its integrations can produce some additional metrics that can provide useful insight into the performance of your application. These metrics are collected with `dogstatsd-ruby`, and can be sent to the same Datadog agent to which you send your traces.
|
2426
|
+
|
2427
|
+
To configure your application for metrics collection:
|
2428
|
+
|
2429
|
+
1. [Configure your Datadog agent for StatsD](https://docs.datadoghq.com/developers/dogstatsd/#setup)
|
2430
|
+
2. Add `gem 'dogstatsd-ruby'` to your Gemfile
|
2431
|
+
|
2432
|
+
#### For application runtime
|
2433
|
+
|
2434
|
+
If runtime metrics are configured, the trace library will automatically collect and send metrics about the health of your application.
|
2435
|
+
|
2436
|
+
To configure runtime metrics, add the following configuration:
|
2437
|
+
|
2438
|
+
```ruby
|
2439
|
+
# config/initializers/datadog.rb
|
2440
|
+
require 'datadog/statsd'
|
2441
|
+
require 'ddtrace'
|
2442
|
+
|
2443
|
+
Datadog.configure do |c|
|
2444
|
+
# To enable runtime metrics collection, set `true`. Defaults to `false`
|
2445
|
+
# You can also set DD_RUNTIME_METRICS_ENABLED=true to configure this.
|
2446
|
+
c.runtime_metrics.enabled = true
|
2447
|
+
|
2448
|
+
# Optionally, you can configure the Statsd instance used for sending runtime metrics.
|
2449
|
+
# Statsd is automatically configured with default settings if `dogstatsd-ruby` is available.
|
2450
|
+
# You can configure with host and port of Datadog agent; defaults to 'localhost:8125'.
|
2451
|
+
c.runtime_metrics.statsd = Datadog::Statsd.new
|
2452
|
+
end
|
2453
|
+
```
|
2454
|
+
|
2455
|
+
See the [Dogstatsd documentation](https://www.rubydoc.info/github/DataDog/dogstatsd-ruby/master/frames) for more details about configuring `Datadog::Statsd`.
|
2456
|
+
|
2457
|
+
The stats are VM specific and will include:
|
2458
|
+
|
2459
|
+
| Name | Type | Description |
|
2460
|
+
| -------------------------- | ------- | -------------------------------------------------------- |
|
2461
|
+
| `runtime.ruby.class_count` | `gauge` | Number of classes in memory space. |
|
2462
|
+
| `runtime.ruby.thread_count` | `gauge` | Number of threads. |
|
2463
|
+
| `runtime.ruby.gc.*`. | `gauge` | Garbage collection statistics: collected from `GC.stat`. |
|
2464
|
+
|
2465
|
+
In addition, all metrics include the following tags:
|
2466
|
+
|
2467
|
+
| Name | Description |
|
2468
|
+
| ------------ | ------------------------------------------------------- |
|
2469
|
+
| `language` | Programming language traced. (e.g. `ruby`) |
|
2470
|
+
| `service` | List of services this associated with this metric. |
|
2471
|
+
|
2472
|
+
### OpenTracing
|
2473
|
+
|
2474
|
+
For setting up Datadog with OpenTracing, see out [Quickstart for OpenTracing](#quickstart-for-opentracing) section for details.
|
2475
|
+
|
2476
|
+
**Configuring Datadog tracer settings**
|
2477
|
+
|
2478
|
+
The underlying Datadog tracer can be configured by passing options (which match `Datadog::Tracer`) when configuring the global tracer:
|
2479
|
+
|
2480
|
+
```ruby
|
2481
|
+
# Where `options` is a Hash of options provided to Datadog::Tracer
|
2482
|
+
OpenTracing.global_tracer = Datadog::OpenTracer::Tracer.new(options)
|
2483
|
+
```
|
2484
|
+
|
2485
|
+
It can also be configured by using `Datadog.configure` described in the [Tracer settings](#tracer-settings) section.
|
2486
|
+
|
2487
|
+
**Activating and configuring integrations**
|
2488
|
+
|
2489
|
+
By default, configuring OpenTracing with Datadog will not automatically activate any additional instrumentation provided by Datadog. You will only receive spans and traces from OpenTracing instrumentation you have in your application.
|
2490
|
+
|
2491
|
+
However, additional instrumentation provided by Datadog can be activated alongside OpenTracing using `Datadog.configure`, which can be used to enhance your tracing further. To activate this, see [Integration instrumentation](#integration-instrumentation) for more details.
|
2492
|
+
|
2493
|
+
**Supported serialization formats**
|
2494
|
+
|
2495
|
+
| Type | Supported? | Additional information |
|
2496
|
+
| ------------------------------ | ---------- | ---------------------- |
|
2497
|
+
| `OpenTracing::FORMAT_TEXT_MAP` | Yes | |
|
2498
|
+
| `OpenTracing::FORMAT_RACK` | Yes | Because of the loss of resolution in the Rack format, please note that baggage items with names containing either upper case characters or `-` will be converted to lower case and `_` in a round-trip respectively. We recommend avoiding these characters or accommodating accordingly on the receiving end. |
|
2499
|
+
| `OpenTracing::FORMAT_BINARY` | No | |
|