Skip to content

Commit

Permalink
Merge pull request #1167 from DataDog/revert_rum_injection
Browse files Browse the repository at this point in the history 
[poc]: revert rum injection poc on master for now
  • Loading branch information
@ericmustin
ericmustin authored Sep 4, 2020
2 parents 7eb8bea + bbc0eea commit d4f311d
Show file tree
Hide file tree
Showing 15 changed files with 1 addition and 1,293 deletions.
92 changes: 0 additions & 92 deletions docs/GettingStarted.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,6 @@ To contribute, check out the [contribution guidelines][contribution docs] and [d
- [Priority sampling](#priority-sampling)
- [Distributed tracing](#distributed-tracing)
- [HTTP request queuing](#http-request-queuing)
- [RUM Injection](#rum-injection)
- [Processing pipeline](#processing-pipeline)
- [Filtering](#filtering)
- [Processing](#processing)
Expand Down Expand Up @@ -1196,12 +1195,9 @@ Where `options` is an optional `Hash` that accepts the following parameters:
| `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` |
| `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` |
| `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` |
| `rum_injection_enabled` | Connect frontend traces from the RUM (real user monitoring) [`browser-sdk`](https://docs.datadoghq.com/real_user_monitoring/installation/?tab=us) to backend traces by automatically injecting an HTML Comment containing the datadog trace-id. This only is applies to html and xhtml pages which are not cached, as determined by HTTP response headers. See [RUM Injection](#rum-injection) for setup details. Set to `true` to enable. Environment Variable: `DD_TRACE_RUM_INJECT_TRACE`. *Experimental* | `false` |
| `rum_injection_disabled_paths` | Define which pages to exclude from automatically injecting an HTML Comment containing the Datadoog trace-id. See [RUM Injection](#rum-injection) for setup details. Accepts an array of path values, including globbed paths e.g. `['/admin', 'api/**/update']`. Environment Variable: `DD_TRACE_CACHED_PAGES`, accepts a CSV formatted string. *Experimental* | `[]` |
| `service_name` | Service name used for `rack` instrumentation | `'rack'` |
| `web_service_name` | Service name for frontend server request queuing spans. (e.g. `'nginx'`) | `'web-server'` |
**Configuring URL quantization behavior**
```ruby
Expand Down Expand Up @@ -1751,8 +1747,6 @@ Other Environment Variables:
- `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.
- `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`.
- `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`.
- `DD_TRACE_RUM_INJECT_TRACE`: Connect frontend traces from the RUM (real user monitoring) [`browser-sdk`](https://docs.datadoghq.com/real_user_monitoring/installation/?tab=us) to backend traces by automatically injecting an HTML Comment containing the datadog trace-id. See [RUM Injection](#rum-injection) for setup details. Set to `true` to enable. Accepts a boolean (default `false`) e.g. `DD_TRACE_RUM_INJECT_TRACE=true`. *experimental*.
- `DD_TRACE_CACHED_PAGES`: Define which pages to exclude from automatically injecting an HTML Comment containing the Datadoog trace-id. See [RUM Injection](#rum-injection) for setup details. Accepts a CSV formatted string (default `''`) of path values, including globbed paths e.g. `DD_TRACE_CACHED_PAGES=/admin,api/**/update`. *Experimental*
- `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`.

### Sampling
Expand Down Expand Up @@ -1969,92 +1963,6 @@ Then you must enable the request queuing feature in the integration handling the

For Rack-based applications, see the [documentation](#rack) for details for enabling this feature.

### RUM Injection

This feature is used in conjunction with Datadog [Real User Monitoring (RUM)](https://docs.datadoghq.com/real_user_monitoring/), which enables end-to-end visibility into real-time activity of individual users in web and mobile applications. In order to captura an initial request's page load times it is necesary to connect front-end and back-end tracing. This is accomplished via our RUM Injection Rack Middleware, which injects the trace-id into eligble html responses via an HTML Comment for Rack based applications. The trace-id can then be used to connect the trace associated with the initial request with the rest of the User's RUM Session.

This functionality is **experimental** and deactivated by default.

To activate this feature, first you must set the rum injection configuration option `rum_injection_enabled` to `true` in the `rack` integration. Additionally, you can use the `rack` configuration option `rum_injection_disabled_paths` to designate a list of any Paths that include cached HTML and should therefore not have a trace-id injected. `rum_injection_disabled_paths` should be set to an array of url Paths, including globbed urls. The following is an example:

```ruby
Datadog.configure do |c|
c.use :rack, rum_injection_enabled: true, rum_injection_disabled_paths: ['/api', '/blog/**/**']
end
```

Review the Rack [documentation](#rack) for more configuration details.

When the Rack RUM Injection Middlewarre is used in conjunction with the Ruby on Rails instrumentation, the middleware is automatically inserted into your application's rack middleware stack in the appropriate location. Here is an example configuration:


```ruby
Datadog.configure do |c|
c.use :rack, rum_injection_enabled: true, rum_injection_disabled_paths: ['/api', '/blog/**/**']
c.use :rails
end
```

However, when using Rack as a standalone application or in conjunction with another web framework, such as Sinatra, you must manually insert the Rack RUM Injection Middleware at the appropriate location within the middleware stack, via `use Datadog::Contrib::Rack::RumInjection`. It should be the _last_ middleware in the stack, and come _after_ any compression middleware such as `Rack::Deflater`

```ruby
# config.ru example
require 'ddtrace'

Datadog.configure do |c|
c.use :rack, options
end

use Datadog::Contrib::Rack::TraceMiddleware
use Rack::Deflater
use Datadog::Contrib::Rack::RumInjection

app = proc do |env|
[ 200, {'Content-Type' => 'text/plain'}, ['OK'] ]
end

run app
```

Last, ensure the [`browser-sdk`](https://docs.datadoghq.com/real_user_monitoring/installation/?tab=us) is setup correctly in your front-end web application.

The RUM Injection middleware will insert an HTML comment into only those responses that are `Content-Type` `html` or `xhtml`, can be reasonably determined to be non-cached html responses at either browser or CDN level, are not streaming responses, and are not compressed or gzipped at time of injection.

#### RUM Manual Injection

For users that have a caching strategy for their HTML that leverages a CDN, VCL, or custom caching rules, the automatic RUM Injection may not be suitable for determining which html templates are not cached, and should have a trace-id injected. In this case, we also provide a Manual Injection option so that users can configure which HTML templates specifically they should inject the trace-id into. The Manual Injection template helpers inject an HTML `<meta>` tag containing the `dd-trace-id` and `dd-trace-time`. This allows the [`browser-sdk`](https://docs.datadoghq.com/real_user_monitoring/installation/?tab=us) to connect frontend sessions to backend traces. To modify a template, add the template helper to generate the RUM Injection meta tags (we recommend `<head>` section of your template, but it can be added anywhere)

To ensure that the automatic RUM Injection's HTML Comment insertion Rack Middleware is also disabled for the template, optionally pass in the rack environment to the helper. The rack environment variable may vary from framework to framework but is usually available with any rack compatible web framework. Below are examples of popular frameworks:

##### Rack with Rails RUM Manual Injection

```
# application.html.erb
<head>
<%= ::Datadog::Contrib::Rack::RumInjection.inject_rum_data(request.env) %>
... existing template code ...
</head>
```

##### Rack with Sinatra RUM Manual Injection

```
<head>
<%= ::Datadog::Contrib::Rack::RumInjection.inject_rum_data(env) %>
... existing template code ...
</head>
```

##### Rack with Generic Web Framework RUM Manual Injection

```
<head>
<%= ::Datadog::Contrib::Rack::RumInjection.inject_rum_data(<RACK_ENVIRONMENT>) %>
... existing template code ...
</head>
```

### Processing Pipeline

Some applications might require that traces be altered or filtered out before they are sent upstream. The processing pipeline allows users to create *processors* to define such behavior.
Expand Down
10 changes: 0 additions & 10 deletions lib/ddtrace/contrib/rack/configuration/settings.rb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,16 +39,6 @@ class Settings < Contrib::Configuration::Settings
option :service_name, default: Ext::SERVICE_NAME

option :web_service_name, default: Ext::WEBSERVER_SERVICE_NAME

option :rum_injection_enabled do |o|
o.default { env_to_bool(Ext::ENV_RUM_INJECTION, false) }
o.lazy
end

option :rum_injection_disabled_paths do |o|
o.default { env_to_list(Ext::ENV_TRACE_CACHED_PAGES, []) }
o.lazy
end
end
end
end
Expand Down
2 changes: 0 additions & 2 deletions lib/ddtrace/contrib/rack/ext.rb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,6 @@ module Ext
SPAN_REQUEST = 'rack.request'.freeze
WEBSERVER_APP = 'webserver'.freeze
WEBSERVER_SERVICE_NAME = 'web-server'.freeze
ENV_TRACE_CACHED_PAGES = 'DD_TRACE_CACHED_PAGES'.freeze
ENV_RUM_INJECTION = 'DD_TRACE_RUM_INJECT_TRACE'.freeze
end
end
end
Expand Down
Loading

0 comments on commit d4f311d

Please sign in to comment.