Module: Datadog::Kit::AppSec::Events::V2

Defined in:
lib/datadog/kit/appsec/events/v2.rb

Overview

The second version of Business Logic Events SDK

Constant Summary collapse

SIGNUP_EVENT = 
"users.signup"
LOGIN_SUCCESS_EVENT = 
"users.login.success"
LOGIN_FAILURE_EVENT = 
"users.login.failure"
TELEMETRY_METRICS_NAMESPACE = 
"appsec"
TELEMETRY_METRICS_SDK_EVENT = 
"sdk.event"
TELEMETRY_METRICS_SDK_VERSION = 
"v2"
TELEMETRY_METRICS_EVENTS_INTO_TYPES = 
{
  LOGIN_SUCCESS_EVENT => "login_success",
  LOGIN_FAILURE_EVENT => "login_failure",
  SIGNUP_EVENT => "signup",
}.freeze

Class Method Summary collapse

Class Method Details

.track_user_login_failure(login, user_exists = false, metadata = {}) ⇒ void

This method returns an undefined value.

Attach user login failure information to the service entry span and trigger AppSec event processing.

Examples:

Login only

Datadog::Kit::AppSec::Events::V2.('[email protected]')

With user existence and metadata

Datadog::Kit::AppSec::Events::V2.(
  '[email protected]',
  true,
  ip: '192.168.1.1', device: 'mobile', 'usr.country': 'US'
)

Parameters:

  • login (String) —

    The user login (e.g., username or email).

  • user_exists (Boolean) (defaults to: false) —

    Whether the user exists in the system.

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

    Additional flat free-form metadata to attach to the event.

Raises:

  • (TypeError) 


99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/datadog/kit/appsec/events/v2.rb', line 99

def (, user_exists = false, metadata = {})
  trace = service_entry_trace
  span = service_entry_span

  if trace.nil? || span.nil?
    return Datadog.logger.warn(
      "Kit::AppSec: Tracing is not enabled. Please enable tracing if you want to track events"
    )
  end

  raise TypeError, "`login` argument must be a String" unless .is_a?(String)
  raise TypeError, "`metadata` argument must be a Hash" unless metadata.is_a?(Hash)

  unless user_exists.is_a?(TrueClass) || user_exists.is_a?(FalseClass)
    raise TypeError, "`user_exists` argument must be a boolean"
  end

  set_span_tags(span, metadata, namespace: LOGIN_FAILURE_EVENT)
  span.set_tag("appsec.events.users.login.failure.track", "true")
  span.set_tag("_dd.appsec.events.users.login.failure.sdk", "true")
  span.set_tag("appsec.events.users.login.failure.usr.login", )
  span.set_tag("appsec.events.users.login.failure.usr.exists", user_exists.to_s)

  ::Datadog::AppSec::TraceKeeper.keep!(trace)

  record_event_telemetry_metric(LOGIN_FAILURE_EVENT)
  ::Datadog::AppSec::Instrumentation.gateway.push("appsec.events.user_lifecycle", LOGIN_FAILURE_EVENT)

  user = ::Datadog::AppSec::Instrumentation::Gateway::User.new(nil, )
  ::Datadog::AppSec::Instrumentation.gateway.push("identity.set_user", user)
end

.track_user_login_success(login, user_or_id = nil, metadata = {}) ⇒ void

This method returns an undefined value.

Attach user login success information to the service entry span and trigger AppSec event processing.

Examples:

Login only

Datadog::Kit::AppSec::Events::V2.('[email protected]')

Login and user attributes

Datadog::Kit::AppSec::Events::V2.(
  '[email protected]',
  { id: 'user-123', email: '[email protected]', name: 'Alice' },
  ip: '192.168.1.1', device: 'mobile', 'usr.country': 'US'
)

Parameters:

  • login (String) —

    The user login (e.g., username or email).

  • user_or_id (String, Hash<Symbol, String>) (defaults to: nil) —

    (optional) If a String, considered as a user ID, if a Hash, considered as a user attributes. The Hash must include :id as a key.

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

    Additional flat free-form metadata to attach to the event.

Raises:

  • (TypeError) 


47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
 
# File 'lib/datadog/kit/appsec/events/v2.rb', line 47

def (, user_or_id = nil, metadata = {})
  trace = service_entry_trace
  span = service_entry_span

  if trace.nil? || span.nil?
    return Datadog.logger.warn(
      "Kit::AppSec: Tracing is not enabled. Please enable tracing if you want to track events"
    )
  end

  raise TypeError, "`login` argument must be a String" unless .is_a?(String)
  raise TypeError, "`metadata` argument must be a Hash" unless metadata.is_a?(Hash)

  user_attributes = build_user_attributes(user_or_id, )

  set_span_tags(span, metadata, namespace: LOGIN_SUCCESS_EVENT)
  set_span_tags(span, user_attributes, namespace: "#{LOGIN_SUCCESS_EVENT}.usr")
  span.set_tag("appsec.events.users.login.success.track", "true")
  span.set_tag("_dd.appsec.events.users.login.success.sdk", "true")

  ::Datadog::AppSec::TraceKeeper.keep!(trace)

  record_event_telemetry_metric(LOGIN_SUCCESS_EVENT)
  ::Datadog::AppSec::Instrumentation.gateway.push("appsec.events.user_lifecycle", LOGIN_SUCCESS_EVENT)

  return Kit::Identity.set_user(trace, span, **user_attributes) if user_attributes.key?(:id)

  # NOTE: This is a fallback for the case when we don't have an ID,
  #       but need to trigger WAF.
  user = ::Datadog::AppSec::Instrumentation::Gateway::User.new(nil, )
  ::Datadog::AppSec::Instrumentation.gateway.push("identity.set_user", user)
end

.track_user_signup(login, user_or_id = nil, metadata = {}) ⇒ void

This method returns an undefined value.

Attach user signup information to the service entry span and trigger AppSec event processing.

Examples:

Login only

Datadog::Kit::AppSec::Events::V2.('[email protected]')

Login, user attributes, and metadata

Datadog::Kit::AppSec::Events::V2.(
  '[email protected]',
  { id: 'user-123', email: '[email protected]', name: 'Alice' },
  ip: '192.168.1.1', device: 'mobile', 'usr.country': 'US'
)

Parameters:

  • login (String) —

    The user login (e.g., username or email).

  • user_or_id (String, Hash<Symbol, String>) (defaults to: nil) —

    (optional) If a String, considered as a user ID, if a Hash, considered as a user attributes. The Hash must include :id as a key.

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

    Additional flat free-form metadata to attach to the event.

Raises:

  • (TypeError) 


152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
 
# File 'lib/datadog/kit/appsec/events/v2.rb', line 152

def (, user_or_id = nil, metadata = {})
  trace = service_entry_trace
  span = service_entry_span

  if trace.nil? || span.nil?
    return Datadog.logger.warn(
      "Kit::AppSec: Tracing is not enabled. Please enable tracing if you want to track events"
    )
  end

  raise TypeError, "`login` argument must be a String" unless .is_a?(String)
  raise TypeError, "`metadata` argument must be a Hash" unless metadata.is_a?(Hash)

  user_attributes = build_user_attributes(user_or_id, )

  set_span_tags(span, metadata, namespace: SIGNUP_EVENT)
  set_span_tags(span, user_attributes, namespace: "#{SIGNUP_EVENT}.usr")
  span.set_tag("appsec.events.users.signup.track", "true")
  span.set_tag("_dd.appsec.events.users.signup.sdk", "true")

  ::Datadog::AppSec::TraceKeeper.keep!(trace)

  record_event_telemetry_metric(SIGNUP_EVENT)

  if user_attributes.key?(:id)
    Kit::Identity.set_user(trace, span, **user_attributes)
  else
    # NOTE: {Datadog::Kit::Identity.set_user} requires an ID,
    #       but WAF can evaluate login alone
    user = ::Datadog::AppSec::Instrumentation::Gateway::User.new(nil, )
    ::Datadog::AppSec::Instrumentation.gateway.push("identity.set_user", user)
  end
end