ddtrace 0.54.2 → 1.8.0

data/README.md

@@ -1,13 +1,17 @@
 # Datadog Trace Client
 
+[![Gem](https://img.shields.io/gem/v/ddtrace)](https://rubygems.org/gems/ddtrace/)
 [![CircleCI](https://circleci.com/gh/DataDog/dd-trace-rb/tree/master.svg?style=svg&circle-token=b0bd5ef866ec7f7b018f48731bb495f2d1372cc1)](https://circleci.com/gh/DataDog/dd-trace-rb/tree/master)
 [![codecov](https://codecov.io/gh/DataDog/dd-trace-rb/branch/master/graph/badge.svg)](https://app.codecov.io/gh/DataDog/dd-trace-rb/branch/master)
+[![YARD documentation](https://img.shields.io/badge/YARD-documentation-blue)](https://s3.amazonaws.com/gems.datadoghq.com/trace/docs/index.html)
 
 ``ddtrace`` is Datadog’s tracing client for Ruby. It is used to trace requests as they flow across web servers,
 databases and microservices so that developers have great visiblity into bottlenecks and troublesome requests.
 
 ## Getting started
 
+**If you're upgrading from a 0.x version, check out our [upgrade guide](https://github.com/DataDog/dd-trace-rb/blob/master/docs/UpgradeGuide.md#from-0x-to-10).**
+
 For a basic product overview, check out our [setup documentation][setup docs].
 
 For installation, configuration, and details about using the API, check out our [API documentation][api docs] and [gem documentation][gem docs].
@@ -18,7 +22,12 @@ For contributing, checkout the [contribution guidelines][contribution docs] and
 
 [setup docs]: https://docs.datadoghq.com/tracing/setup/ruby/
 [api docs]: https://github.com/DataDog/dd-trace-rb/blob/master/docs/GettingStarted.md
-[gem docs]: http://gems.datadoghq.com/trace/docs/
+[gem docs]: https://s3.amazonaws.com/gems.datadoghq.com/trace/docs/index.html
 [visualization docs]: https://docs.datadoghq.com/tracing/visualization/
 [contribution docs]: https://github.com/DataDog/dd-trace-rb/blob/master/CONTRIBUTING.md
 [development docs]: https://github.com/DataDog/dd-trace-rb/blob/master/docs/DevelopmentGuide.md
+
+## Special thanks
+
+* [Mike Fiedler](https://github.com/miketheman) for working on a number of Datadog Ruby projects, as well as graciously
+  gifting control of the `datadog` gem

data/bin/ddtracerb

@@ -1,15 +1,15 @@
 #!/usr/bin/env ruby
-require 'ddtrace/tasks/exec'
-require 'ddtrace/tasks/help'
+require 'datadog/profiling/tasks/exec'
+require 'datadog/profiling/tasks/help'
 
 command = ARGV.shift
 
 case command
 when 'exec'
-  Datadog::Tasks::Exec.new(ARGV).run
+  Datadog::Profiling::Tasks::Exec.new(ARGV).run
 when 'help', '--help'
-  Datadog::Tasks::Help.new.run
+  Datadog::Profiling::Tasks::Help.new.run
 else
   puts "Command '#{command}' is not valid for ddtrace."
-  Datadog::Tasks::Help.new.run
+  Datadog::Profiling::Tasks::Help.new.run
 end

data/ext/ddtrace_profiling_loader/ddtrace_profiling_loader.c

@@ -0,0 +1,134 @@
+#include <stdbool.h>
+#include <dlfcn.h>
+#include <ruby.h>
+
+// Why this exists:
+//
+// The Datadog::Profiling::Loader exists because when Ruby loads a native extension (using `require`), it uses
+// `dlopen(..., RTLD_LAZY | RTLD_GLOBAL)` (https://github.com/ruby/ruby/blob/67950a4c0a884bdb78d9beb4405ebf7459229b21/dln.c#L362).
+// This means that every symbol exposed directly or indirectly by that native extension becomes visible to every other
+// extension in the Ruby process. This can cause issues, see https://github.com/rubyjs/mini_racer/pull/179.
+//
+// Instead of `RTLD_LAZY | RTLD_GLOBAL`, we want to call `dlopen` with `RTLD_LAZY | RTLD_LOCAL | RTLD_DEEPBIND` when
+// loading the profiling native extension, to avoid leaking any unintended symbols (`RTLD_LOCAL`) and avoid picking
+// up other's symbols (`RTLD_DEEPBIND`).
+//
+// But Ruby's extension loading mechanism is not configurable -- there's no way to tell it to use different flags when
+// calling `dlopen`. To get around this, this file (ddtrace_profiling_loader.c) introduces another extension
+// (profiling loader) which has only a single responsibility: mimic Ruby's extension loading mechanism, but when calling
+// `dlopen` use a different set of flags.
+// This idea was shamelessly stolen from @lloeki's work in https://github.com/rubyjs/mini_racer/pull/179, big thanks!
+//
+// Extra note: Currently (May 2022), that we know of, the profiling native extension only exposes one potentially
+// problematic symbol: `rust_eh_personality` (coming from libdatadog).
+// Future versions of Rust have been patched not to expose this
+// (see https://github.com/rust-lang/rust/pull/95604#issuecomment-1108563434) so we may want to revisit the need
+// for this loader in the future, and perhaps delete it if we no longer require its services :)
+
+#ifndef RTLD_DEEPBIND
+  #define RTLD_DEEPBIND 0
+#endif
+
+// Used to mark function arguments that are deliberately left unused
+#ifdef __GNUC__
+  #define DDTRACE_UNUSED  __attribute__((unused))
+#else
+  #define DDTRACE_UNUSED
+#endif
+
+static VALUE ok_symbol = Qnil; // :ok in Ruby
+static VALUE error_symbol = Qnil; // :error in Ruby
+
+static VALUE _native_load(DDTRACE_UNUSED VALUE self, VALUE ruby_path, VALUE ruby_init_name);
+static bool failed_to_load(void *handle, VALUE *failure_details);
+static bool incompatible_library(void *handle, VALUE *failure_details);
+static bool failed_to_initialize(void *handle, char *init_name, VALUE *failure_details);
+static void set_failure_from_dlerror(VALUE *failure_details);
+static void unload_failed_library(void *handle);
+
+#define DDTRACE_EXPORT __attribute__ ((visibility ("default")))
+
+void DDTRACE_EXPORT Init_ddtrace_profiling_loader(void) {
+  VALUE datadog_module = rb_define_module("Datadog");
+  VALUE profiling_module = rb_define_module_under(datadog_module, "Profiling");
+  VALUE loader_module = rb_define_module_under(profiling_module, "Loader");
+  rb_define_singleton_method(loader_module, "_native_load", _native_load, 2);
+
+  ok_symbol = ID2SYM(rb_intern_const("ok"));
+  error_symbol = ID2SYM(rb_intern_const("error"));
+}
+
+static VALUE _native_load(DDTRACE_UNUSED VALUE self, VALUE ruby_path, VALUE ruby_init_name) {
+  Check_Type(ruby_path, T_STRING);
+  Check_Type(ruby_init_name, T_STRING);
+
+  char *path = StringValueCStr(ruby_path);
+  char *init_name = StringValueCStr(ruby_init_name);
+
+  void *handle = dlopen(path, RTLD_LAZY | RTLD_LOCAL | RTLD_DEEPBIND);
+
+  VALUE failure_details = Qnil;
+
+  if (
+    failed_to_load(handle, &failure_details) ||
+    incompatible_library(handle, &failure_details) ||
+    failed_to_initialize(handle, init_name, &failure_details)
+  ) {
+    return rb_ary_new_from_args(2, error_symbol, failure_details);
+  }
+
+  return rb_ary_new_from_args(2, ok_symbol, Qnil);
+}
+
+static bool failed_to_load(void *handle, VALUE *failure_details) {
+  if (handle == NULL) {
+    set_failure_from_dlerror(failure_details);
+    return true;
+  } else {
+    return false;
+  }
+}
+
+static bool incompatible_library(void *handle, VALUE *failure_details) {
+  // The library being loaded may be linked to a different libruby than the current executing Ruby.
+  // We check if this is the case by checking if a well-known symbol resolves to a common address.
+
+  void *xmalloc_from_library = dlsym(handle, "ruby_xmalloc");
+
+  if (xmalloc_from_library == NULL) {
+    // This happens when ruby is built without a `libruby.so` by using `--disable-shared` at compilation time.
+    // In this situation, no conflict between libruby version is possible.
+    return false;
+  }
+
+  if (xmalloc_from_library != &ruby_xmalloc) {
+    *failure_details = rb_str_new_cstr("library was compiled and linked to a different Ruby version");
+    unload_failed_library(handle);
+    return true;
+  } else {
+    return false;
+  }
+}
+
+static bool failed_to_initialize(void *handle, char *init_name, VALUE *failure_details) {
+  void (*initialization_function)(void) = dlsym(handle, init_name);
+
+  if (initialization_function == NULL) {
+    set_failure_from_dlerror(failure_details);
+    unload_failed_library(handle);
+    return true;
+  } else {
+    (*initialization_function)();
+    return false;
+  }
+}
+
+static void set_failure_from_dlerror(VALUE *failure_details) {
+  char *failure = dlerror();
+  *failure_details = failure == NULL ? Qnil : rb_str_new_cstr(failure);
+}
+
+static void unload_failed_library(void *handle) {
+  // Note: According to the Ruby VM sources, this may fail with a segfault on really old versions of macOS (< 10.11)
+  dlclose(handle);
+}

data/ext/ddtrace_profiling_loader/extconf.rb

@@ -0,0 +1,74 @@
+# typed: ignore
+
+# rubocop:disable Style/StderrPuts
+# rubocop:disable Style/GlobalVars
+
+if RUBY_ENGINE != 'ruby' || Gem.win_platform?
+  $stderr.puts(
+    'WARN: Skipping build of ddtrace profiling loader. See ddtrace profiling native extension note for details.'
+  )
+
+  File.write('Makefile', 'all install clean: # dummy makefile that does nothing')
+  exit
+end
+
+require 'mkmf'
+
+# mkmf on modern Rubies actually has an append_cflags that does something similar
+# (see https://github.com/ruby/ruby/pull/5760), but as usual we need a bit more boilerplate to deal with legacy Rubies
+def add_compiler_flag(flag)
+  if try_cflags(flag)
+    $CFLAGS << ' ' << flag
+  else
+    $stderr.puts("WARNING: '#{flag}' not accepted by compiler, skipping it")
+  end
+end
+
+# Because we can't control what compiler versions our customers use, shipping with -Werror by default is a no-go.
+# But we can enable it in CI, so that we quickly spot any new warnings that just got introduced.
+add_compiler_flag '-Werror' if ENV['DDTRACE_CI'] == 'true'
+
+# Older gcc releases may not default to C99 and we need to ask for this. This is also used:
+# * by upstream Ruby -- search for gnu99 in the codebase
+# * by msgpack, another ddtrace dependency
+#   (https://github.com/msgpack/msgpack-ruby/blob/18ce08f6d612fe973843c366ac9a0b74c4e50599/ext/msgpack/extconf.rb#L8)
+add_compiler_flag '-std=gnu99'
+
+# Gets really noisy when we include the MJIT header, let's omit it (TODO: Use #pragma GCC diagnostic instead?)
+add_compiler_flag '-Wno-unused-function'
+
+# Allow defining variables at any point in a function
+add_compiler_flag '-Wno-declaration-after-statement'
+
+# If we forget to include a Ruby header, the function call may still appear to work, but then
+# cause a segfault later. Let's ensure that never happens.
+add_compiler_flag '-Werror-implicit-function-declaration'
+
+# Warn on unused parameters to functions. Use `DDTRACE_UNUSED` to mark things as known-to-not-be-used.
+add_compiler_flag '-Wunused-parameter'
+
+# The native extension is not intended to expose any symbols/functions for other native libraries to use;
+# the sole exception being `Init_ddtrace_profiling_loader` which needs to be visible for Ruby to call it when
+# it `dlopen`s the library.
+#
+# By setting this compiler flag, we tell it to assume that everything is private unless explicitly stated.
+# For more details see https://gcc.gnu.org/wiki/Visibility
+add_compiler_flag '-fvisibility=hidden'
+
+# Avoid legacy C definitions
+add_compiler_flag '-Wold-style-definition'
+
+# Enable all other compiler warnings
+add_compiler_flag '-Wall'
+add_compiler_flag '-Wextra'
+
+# Tag the native extension library with the Ruby version and Ruby platform.
+# This makes it easier for development (avoids "oops I forgot to rebuild when I switched my Ruby") and ensures that
+# the wrong library is never loaded.
+# When requiring, we need to use the exact same string, including the version and the platform.
+EXTENSION_NAME = "ddtrace_profiling_loader.#{RUBY_VERSION}_#{RUBY_PLATFORM}".freeze
+
+create_makefile(EXTENSION_NAME)
+
+# rubocop:enable Style/GlobalVars
+# rubocop:enable Style/StderrPuts

data/ext/ddtrace_profiling_native_extension/NativeExtensionDesign.md

@@ -1,32 +1,66 @@
 # Profiling Native Extension Design
 
-The profiling native extension is used to implement features which are expensive (in terms of resources) or otherwise
-impossible to implement using Ruby code.
+The profiling native extension is used to:
 
-This extension is quite coupled with MRI Ruby ("C Ruby") internals, and is not intended to support other rubies such as
+1. Implement features which are expensive (in terms of resources) or otherwise impossible to implement using Ruby code.
+2. Bridge between Ruby-specific profiling features and [`libdatadog`](https://github.com/DataDog/libdatadog), a Rust-based
+library with common profiling functionality.
+
+Due to (1), this extension is quite coupled with MRI Ruby ("C Ruby") internals, and is not intended to support other rubies such as
 JRuby or TruffleRuby. When below we say "Ruby", read it as "MRI Ruby".
 
 ## Disabling
 
-The profiling native extension can be disabled by setting `DD_PROFILING_NO_EXTENSION=true` when installing or running
+The profiling native extension can be disabled by setting `DD_PROFILING_NO_EXTENSION=true` when installing
 the gem. Setting `DD_PROFILING_NO_EXTENSION` at installation time skips compilation of the extension entirely.
 
 (If you're a customer and needed to use this, please tell us why on <https://github.com/DataDog/dd-trace-rb/issues/new>.)
 
-Currently the profiler can still "limp along" when the native extension is disabled, but the plan is to require it
-in future releases -- e.g. disabling the extension will disable profiling entirely.
+In past releases, it was possible for the profiler to run without the native extension, but that's no longer the case,
+and disabling the extension will disable profiling.
+
+## Who is this page for?
+
+**This documentation is intended to be used by dd-trace-rb developers. Please see the `docs/` folder for user-level
+documentation.**
 
-## Safety
+## Must not block or break users that cannot use it
 
 The profiling native extension is (and must always be) designed to **not cause failures** during gem installation, even
 if some features, Ruby versions, or operating systems are not supported.
 
-E.g. the extension must cleanly build on Ruby 2.1 (or the oldest Ruby version we support at the time) on Windows,
+E.g. the extension must not break installation on Ruby 2.1 (or the oldest Ruby version we support at the time) on 64-bit ARM macOS,
 even if at run time it will effectively do nothing for such a setup.
 
 We have a CI setup to help validate this, but this is really important to keep in mind when adding to or changing the
 existing codebase.
 
+## Memory leaks and Interaction with Ruby VM APIs
+
+When adding to or changing the native extension, we must always consider what API calls can lead to Ruby exceptions to
+be raised, and whether there are is dynamically-allocated memory that can be leaked if that happens.
+
+(When a Ruby exception is raised, the VM will use `setjmp` and `longjmp` to jump back in the stack and thus skip
+our clean-up code, like in a Ruby-level exception.)
+
+We avoid issues using a combination of:
+
+* Avoiding dynamic allocation as much as possible
+* Getting all needed data and doing all validations before doing any dynamic allocations
+* Avoiding calling Ruby VM APIs after doing dynamic allocations
+* Wrapping dynamic allocations into Ruby GC-managed objects (using `TypedData_Wrap_Struct`), so that Ruby will manage
+  their lifetime and call `free` when the GC-managed object is no longer being referenced
+* Using [`rb_protect` and similar APIs](https://silverhammermba.github.io/emberb/c/?#rescue) to run cleanup code on
+  exception cases
+
+Non-exhaustive list of APIs that cause exceptions to be raised:
+
+* `Check_TypedStruct`, `Check_Type`, `ENFORCE_TYPE`
+* `rb_funcall`
+* `rb_thread_call_without_gvl`
+* [Numeric conversion APIs, e.g. `NUM2LONG`, `NUM2INT`, etc.](https://silverhammermba.github.io/emberb/c/?#translation)
+* Our `char_slice_from_ruby_string` helper
+
 ## Usage of private VM headers
 
 To implement some of the features below, we sometimes require access to private Ruby header files (that describe VM
@@ -39,6 +73,8 @@ Because these private header files are not included in regular Ruby installation
 
 Functions which make use of these headers are defined in the <private_vm_api_acccess.c> file.
 
+There is currently no way for disabling usage of the private MJIT header for Ruby 2.6+.
+
 **Important Note**: Our medium/long-term plan is to stop relying on all private Ruby headers, and instead request and
 contribute upstream changes so that they become official public VM APIs.
 
@@ -64,7 +100,6 @@ Thus, even though a regular Ruby installation does not include these files, we c
 ## Feature: Getting thread CPU-time clock_ids
 
 * **OS support**: Linux
-* **Ruby support**: 2.6+
 
 To enable CPU-time profiling, we use the `pthread_getcpuclockid(pthread_t thread, clockid_t *clockid)` C function to
 obtain a `clockid_t` that can then be used with the `Process.clock_gettime` method (or directly with the
@@ -84,3 +119,38 @@ Note that `pthread_getcpuclockid()` is not available on macOS (nor, obviously, o
 is currently Linux-specific. Thus, in the <clock_id_from_pthread.c> file we implement the feature for supported Ruby
 setups but if something is missing we instead compile in <clock_id_noop.c> that includes a no-op implementation of the
 feature.
+
+## Fork-safety
+
+It's common for Ruby applications to create child processes via the use of `fork`. For instance, this strategy is used
+by the puma webserver and the resque job processing tool.
+
+Thus, the profiler needs to be designed to take this into account. I'll call out two important parts of this design:
+
+1. Automatically propagate profiler to child processes. To make onboarding easier, we monkey patch the Ruby `fork` APIs
+so that the profiler is automatically restarted in child processes. This way, the user only needs to start profiling at
+the beginning of their application, and automatically forks are profiled as well.
+
+2. The profiler must ensure correctness and stability even if the application forks. There must be no impact on the
+application or incorrect data generated.
+
+### Fork-safety for libdatadog
+
+Since libdatadog is built in native code (Rust), special care needs to be take to consider how we're using it and how
+it can be affected by the use of `fork`.
+
+* Profile-related APIs: `Profile_new` and `Profile_add` and `Profile_free` are only called with the Ruby Global VM Lock
+being held. Thus, if Ruby APIs are being used for fork, this prevents any concurrency between profile mutation and
+forking, because if we’re holding the lock, then no other thread can call into the fork APIs.
+(Calling libc `fork()` directly from a native extension is possible but would break the VM as well, since it does need
+to do some of its own work when forking happens, so we’ll ignore that one)
+
+* Exporter-related APIs: Explicitly to make sure we had no issues with forking, we create a new `CancellationToken_new`
+and `ProfileExporterV3_new` for every report. We do release the Global VM Lock during exporting, so it's possible for
+forking and exporting to be concurrent.
+
+  Both the CancellationToken and ProfileExporter are only referenced on the stack of the thread doing the exporting, so
+  they will not be reused in the child process after the fork. In the worst case, if a report is concurrent with a fork,
+  then it's possible a small amount of memory will not be cleaned up in the child process.
+
+  Because there is no leftover undefined state, we guarantee correctness for the exporter APIs.

data/ext/ddtrace_profiling_native_extension/clock_id.h

@@ -1,4 +1,25 @@
 #pragma once
 
-void self_test_clock_id();
+#include <stdbool.h>
+#include <time.h>
+
+// Contains the operating-system specific identifier needed to fetch CPU-time, and a flag to indicate if we failed to fetch it
+typedef struct thread_cpu_time_id {
+  bool valid;
+  clockid_t clock_id;
+} thread_cpu_time_id;
+
+// Contains the current cpu time, and a flag to indicate if we failed to fetch it
+typedef struct thread_cpu_time {
+  bool valid;
+  long result_ns;
+} thread_cpu_time;
+
+void self_test_clock_id(void);
+
+// TODO: Remove this after the OldStack profiler gets removed
 VALUE clock_id_for(VALUE self, VALUE thread);
+
+// Safety: This function is assumed never to raise exceptions by callers
+thread_cpu_time_id thread_cpu_time_id_for(VALUE thread);
+thread_cpu_time thread_cpu_time_for(thread_cpu_time_id time_id);

data/ext/ddtrace_profiling_native_extension/clock_id_from_pthread.c

@@ -7,28 +7,23 @@
 #include <pthread.h>
 #include <time.h>
 #include <errno.h>
-
 #include <ruby.h>
 
-#ifdef RUBY_2_1_WORKAROUND
-#include <thread_native.h>
-#else
-#include <ruby/thread_native.h>
-#endif
-
+#include "helpers.h"
 #include "private_vm_api_access.h"
-
 #include "clock_id.h"
+#include "time_helpers.h"
 
 // Validate that our home-cooked pthread_id_for() matches pthread_self() for the current thread
-void self_test_clock_id() {
+void self_test_clock_id(void) {
   rb_nativethread_id_t expected_pthread_id = pthread_self();
   rb_nativethread_id_t actual_pthread_id = pthread_id_for(rb_thread_current());
 
   if (expected_pthread_id != actual_pthread_id) rb_raise(rb_eRuntimeError, "pthread_id_for() self-test failed");
 }
 
-VALUE clock_id_for(VALUE self, VALUE thread) {
+// TODO: Remove this after the OldStack profiler gets removed
+VALUE clock_id_for(DDTRACE_UNUSED VALUE _self, VALUE thread) {
   rb_nativethread_id_t thread_id = pthread_id_for(thread);
 
   clockid_t clock_id;
@@ -49,4 +44,32 @@ VALUE clock_id_for(VALUE self, VALUE thread) {
   }
 }
 
+// Safety: This function is assumed never to raise exceptions by callers
+thread_cpu_time_id thread_cpu_time_id_for(VALUE thread) {
+  rb_nativethread_id_t thread_id = pthread_id_for(thread);
+  clockid_t clock_id;
+
+  int error = pthread_getcpuclockid(thread_id, &clock_id);
+
+  if (error == 0) {
+    return (thread_cpu_time_id) {.valid = true, .clock_id = clock_id};
+  } else {
+    // TODO: Include the error code in some way in the output?
+    return (thread_cpu_time_id) {.valid = false};
+  }
+}
+
+thread_cpu_time thread_cpu_time_for(thread_cpu_time_id time_id) {
+  thread_cpu_time error = (thread_cpu_time) {.valid = false};
+
+  if (!time_id.valid) { return error; }
+
+  struct timespec current_cpu;
+
+  // TODO: Include the error code in some way in the output?
+  if (clock_gettime(time_id.clock_id, &current_cpu) != 0) return error;
+
+  return (thread_cpu_time) {.valid = true, .result_ns = current_cpu.tv_nsec + SECONDS_AS_NS(current_cpu.tv_sec)};
+}
+
 #endif

data/ext/ddtrace_profiling_native_extension/clock_id_noop.c

@@ -7,8 +7,17 @@
 #include <ruby.h>
 
 #include "clock_id.h"
+#include "helpers.h"
 
-void self_test_clock_id() { } // Nothing to check
-VALUE clock_id_for(VALUE self, VALUE thread) { return Qnil; } // Nothing to return
+void self_test_clock_id(void) { } // Nothing to check
+VALUE clock_id_for(DDTRACE_UNUSED VALUE _self, DDTRACE_UNUSED VALUE _thread) { return Qnil; } // Nothing to return
+
+thread_cpu_time_id thread_cpu_time_id_for(DDTRACE_UNUSED VALUE _thread) {
+  return (thread_cpu_time_id) {.valid = false};
+}
+
+thread_cpu_time thread_cpu_time_for(DDTRACE_UNUSED thread_cpu_time_id _time_id) {
+  return (thread_cpu_time) {.valid = false};
+}
 
 #endif