Update docs for AppSec on Ruby 1.1.0

content/en/security_platform/application_security/getting_started/ruby.md

@@ -16,7 +16,7 @@ further_reading:
       text: "Troubleshooting Application Security Monitoring"
 ---
 
-You can monitor application security for Ruby apps running in Docker, Kubernetes, AWS ECS, and AWS Fargate. 
+You can monitor application security for Ruby apps running in Docker, Kubernetes, AWS ECS, and AWS Fargate.
 
 {{% appsec-getstarted %}}
 
@@ -25,61 +25,97 @@ You can monitor application security for Ruby apps running in Docker, Kubernetes
 1. **Update your Gemfile to include the Datadog library**:
 
    ```ruby
-   gem 'ddtrace', '~> 1.0'
+   gem 'ddtrace', '~> 1.1'
    ```
 
    For information about which language and framework versions are supported by the library, see [Compatibility][1].
 
    For more information about upgrading from a `dd-trace` 0.x version, see [the Ruby tracer upgrade guide][2].
 
 2. **Enable ASM**, either in your code:
+
+   Note: ASM currently requires the APM tracer to be enabled; a quick setup covering the most common cases is described below, see [the Ruby tracer documentation][3] for more details.
+
    {{< tabs >}}
 
 {{% tab "Rails" %}}
-   Either enable the tracer through auto-instrumentation by updating your Gemfile:
+   Enable the APM tracer manually by adding an initializer in your application code:
+
+   ```ruby
+   # config/initializers/datadog.rb
+
+   require 'datadog/appsec'
+
+   Datadog.configure do |c|
+     # enable the APM tracer
+     c.tracing.instrument :rails
+
+     # enable ASM
+     c.appsec.enabled = true
+     c.appsec.instrument :rails
+   end
+   ```
+
+   Or enable the APM tracer through auto-instrumentation by updating your Gemfile to auto-instrument:
 
    ```ruby
-   gem 'ddtrace', '~> 1.0', require: 'ddtrace/auto_instrument'
+   gem 'ddtrace', '~> 1.1', require: 'ddtrace/auto_instrument'
    ```
 
-   Or enable the tracer by adding an initializer in your application code:
+   And also enable AppSec:
 
    ```ruby
    # config/initializers/datadog.rb
 
    require 'datadog/appsec'
 
    Datadog.configure do |c|
-     # enable the APM tracer
-     # not needed if `gem 'ddtrace', require: 'ddtrace/auto_instrument' is used
-     c.tracing.instrument :rails
+     # the APM tracer is enabled by auto-instrumentation
 
+     # enable ASM
      c.appsec.enabled = true
      c.appsec.instrument :rails
    end
    ```
+
 {{% /tab %}}
 
 {{% tab "Sinatra" %}}
-   Enable the tracer by adding the following to your application's startup:
+   Enable the APM tracer by adding the following to your application's startup:
 
    ```ruby
+   require 'sinatra'
    require 'ddtrace'
    require 'datadog/appsec'
 
    Datadog.configure do |c|
      # enable the APM tracer
      c.tracing.instrument :sinatra
 
-     # enable appsec for Sinatra
+     # enable ASM for Sinatra
+     c.appsec.enabled = true
+     c.appsec.instrument :sinatra
+   end
+   ```
+
+   Or enable the APM tracer through auto-instrumentation:
+
+   ```ruby
+   require 'sinatra'
+   require 'ddtrace/auto_instrument'
+
+   Datadog.configure do |c|
+     # the APM tracer is enabled by auto-instrumentation
+
+     # enable ASM for Sinatra
      c.appsec.enabled = true
      c.appsec.instrument :sinatra
    end
    ```
 {{% /tab %}}
 
 {{% tab "Rack" %}}
-   Enable the tracer by adding the following to your `config.ru` file:
+   Enable the APM tracer by adding the following to your `config.ru` file:
 
    ```ruby
    require 'ddtrace'
@@ -89,7 +125,7 @@ You can monitor application security for Ruby apps running in Docker, Kubernetes
      # enable the APM tracer
      c.tracing.instrument :rack
 
-     # enable appsec for Rack
+     # enable ASM for Rack
      c.appsec.enabled = true
      c.appsec.instrument :rack
    end
@@ -141,7 +177,7 @@ spec:
 {{% /tab %}}
 {{% tab "AWS ECS" %}}
 
-Update your ECS task definition JSON file, by adding this in the  environment section:
+Update your ECS task definition JSON file, by adding this in the environment section:
 
 ```json
 "environment": [
@@ -175,3 +211,4 @@ env DD_APPSEC_ENABLED=true rails server
 
 [1]: /security_platform/application_security/setup_and_configure/?code-lang=ruby#compatibility
 [2]: https://github.com/DataDog/dd-trace-rb/blob/master/docs/UpgradeGuide.md#from-0x-to-10
+[3]: /tracing/setup_overview/setup/ruby/

content/en/security_platform/application_security/setup_and_configure.md

@@ -292,11 +292,51 @@ if span, ok := tracer.SpanFromContext(request.Context()); ok {
 
 {{< programming-lang lang="ruby" >}}
 
+Use either API to add user information to a trace so that you can monitor authenticated requests in the application.
+
+{{< tabs >}}
+
+{{% tab "Using `Datadog::Kit::Identity.set_user` %}}
+
+Starting with `ddtrace` 1.1.0, a convenience `set_user` method is available:
+
+```ruby
+# Get the active trace
+trace = Datadog::Tracing.active_trace
+
+# Set mandatory user id tag
+Datadog::Kit::Identity.set_user(trace, id: 'd131dd02c56eeec4')
+
+# Or set any of these optional user monitoring tags
+Datadog::Kit::Identity.set_user(
+  trace,
+
+  # mandatory id
+  id: 'd131dd02c56eeec4',
+
+  # optional tags with known semantics
+  name: 'Jean Example',
+  email:, '[email protected]',
+  session_id:, '987654321',
+  role: 'admin',
+  scope: 'read:message, write:files',
+
+  # optional free-form tags
+  another_tag: 'another_value',
+)
+```
+
+{{% /tab %}}
+
+{{% tab "Using trace `set_tag`" %}}
+
+Note: `Datadog::Kit::Identity.set_user` is the recommended way to set user information.
+
 Use the the Ruby tracer's API for adding custom tags to a trace, and add user information so that you can monitor authenticated requests in the application.
 
-User monitoring tags are applied on the trace and start with the prefix `usr` followed by the name of the field. For example, `usr.name` is a user monitoring tag that tracks the user’s name.
+User monitoring tags are applied on the trace and start with the prefix `usr.` followed by the name of the field. For example, `usr.name` is a user monitoring tag that tracks the user’s name.
 
-The example below shows how to obtain the root span and add relevant user monitoring tags:
+The example below shows how to obtain the active trace and add relevant user monitoring tags:
 
 **Notes**:
 - Tag values must be strings.
@@ -309,14 +349,21 @@ trace = Datadog::Tracing.active_trace
 # Set mandatory user id tag
 trace.set_tag('usr.id', 'd131dd02c56eeec4')
 
-# Set optional user monitoring tags
+# Set optional user monitoring tags with known sematics
 trace.set_tag('usr.name', 'Jean Example')
 trace.set_tag('usr.email', '[email protected]')
 trace.set_tag('usr.session_id', '987654321')
 trace.set_tag('usr.role', 'admin')
 trace.set_tag('usr.scope', 'read:message, write:files')
+
+# Set free-form tags:
+trace.set_tag('usr.another_tag', 'another_value')
 ```
 
+{{% /tab %}}
+
+{{< /tabs >}}
+
 {{< /programming-lang >}}
 
 {{< programming-lang lang="php" >}}
@@ -386,11 +433,34 @@ The data that you collect with Datadog can contain sensitive information that yo
 
 By default, ASM collects information from suspicious requests to help you understand why the request was flagged as suspicious. Before sending the data, ASM scans it for patterns and keywords that indicate that the data is sensitive. If the data is deemed sensitive, it is replaced with a `<redacted>` flag, so you observe that although the request was suspicious, the request data could not be collected because of data security concerns.
 
-To protect users' data, sensitive data scanning is activated by default in ASM. You can customize the configuration by using the following environment variables. The scanning is based on the [RE2 syntax][2], so to customize scanning, set the value of these environment variables to a valid RE2 patten:
+To protect users' data, sensitive data scanning is activated by default in ASM. You can customize the configuration by using the following environment variables. The scanning is based on the [RE2 syntax][2], so to customize scanning, set the value of these environment variables to a valid RE2 pattern:
 
-* `DD_APPSEC_OBFUSCATION_PARAMETER_KEY_REGEXP` - Pattern for scanning for keys whose values commonly contain sensitive data. If found, the key, all corresponding values, and any child nodes are redacted.
+* `DD_APPSEC_OBFUSCATION_PARAMETER_KEY_REGEXP` - Pattern for scanning for keys whose values commonly contain sensitive data. If found, the values and any child nodes associated with the key are redacted.
 * `DD_APPSEC_OBFUSCATION_PARAMETER_VALUE_REGEXP` - Pattern for scanning for values that could indicate sensitive data. If found, the value and all its child nodes are redacted.
 
+{{< programming-lang-wrapper langs="ruby" >}}
+
+{{< programming-lang lang="ruby" >}}
+
+It is also possible to configure these patterns from code:
+
+```ruby
+Datadog.configure do |c|
+  # ...
+
+  # Set custom RE2 regexes
+  c.appsec.obfuscator_key_regex = '...'
+  c.appsec.obfuscator_value_regex = '...'
+end
+```
+
+Note: this feature is available starting with `ddtrace` 1.1.0.
+
+{{< /programming-lang >}}
+
+{{< /programming-lang-wrapper >}}
+
+
 The following are examples of data that are flagged as sensitive by default:
 
 * `pwd`, `password`, `ipassword`, `pass_phrase`