Add OpenAPI spec for APM spans-public-api trace endpoints

examples/v2/apm-trace/GetPrunedTraceByID.rb

@@ -0,0 +1,8 @@
+# Get a pruned trace by ID returns "OK" response
+
+require "datadog_api_client"
+DatadogAPIClient.configure do |config|
+  config.unstable_operations["v2.get_pruned_trace_by_id".to_sym] = true
+end
+api_instance = DatadogAPIClient::V2::APMTraceAPI.new
+p api_instance.get_pruned_trace_by_id("trace_id")

examples/v2/apm-trace/GetTraceByID.rb

@@ -0,0 +1,8 @@
+# Get a trace by ID returns "OK" response
+
+require "datadog_api_client"
+DatadogAPIClient.configure do |config|
+  config.unstable_operations["v2.get_trace_by_id".to_sym] = true
+end
+api_instance = DatadogAPIClient::V2::APMTraceAPI.new
+p api_instance.get_trace_by_id("trace_id")

features/scenarios_model_mapping.rb

@@ -4219,6 +4219,20 @@
     "v2.ListConnections" => {
             "entity" => "String",
     },
+    "v2.GetPrunedTraceByID" => {
+            "trace_id" => "String",
+            "expand_span_id" => "Integer",
+            "time_hint" => "Integer",
+            "force_source" => "String",
+            "include_path" => "Array<String>",
+            "tag_include" => "Array<String>",
+            "tag_exclude" => "Array<String>",
+            "only_service_entry_spans" => "Boolean",
+    },
+    "v2.GetTraceByID" => {
+            "trace_id" => "String",
+            "include_fields" => "Array<String>",
+    },
     "v2.BatchRowsQuery" => {
             "body" => "BatchRowsQueryRequest",
     },

features/v2/apm_trace.feature

@@ -0,0 +1,48 @@
+@endpoint(apm-trace) @endpoint(apm-trace-v2)
+Feature: APM Trace
+  Retrieve full or pruned APM traces by trace ID.
+
+  Background:
+    Given a valid "apiKeyAuth" key in the system
+    And a valid "appKeyAuth" key in the system
+    And an instance of "APMTrace" API
+
+  @generated @skip @team:DataDog/apm-reliability
+  Scenario: Get a pruned trace by ID returns "Not Found" response
+    Given operation "GetPrunedTraceByID" enabled
+    And new "GetPrunedTraceByID" request
+    And request contains "trace_id" parameter from "REPLACE.ME"
+    When the request is sent
+    Then the response status is 404 Not Found
+
+  @generated @skip @team:DataDog/apm-reliability
+  Scenario: Get a pruned trace by ID returns "OK" response
+    Given operation "GetPrunedTraceByID" enabled
+    And new "GetPrunedTraceByID" request
+    And request contains "trace_id" parameter from "REPLACE.ME"
+    When the request is sent
+    Then the response status is 200 OK
+
+  @generated @skip @team:DataDog/apm-reliability
+  Scenario: Get a trace by ID returns "Not Found" response
+    Given operation "GetTraceByID" enabled
+    And new "GetTraceByID" request
+    And request contains "trace_id" parameter from "REPLACE.ME"
+    When the request is sent
+    Then the response status is 404 Not Found
+
+  @generated @skip @team:DataDog/apm-reliability
+  Scenario: Get a trace by ID returns "OK" response
+    Given operation "GetTraceByID" enabled
+    And new "GetTraceByID" request
+    And request contains "trace_id" parameter from "REPLACE.ME"
+    When the request is sent
+    Then the response status is 200 OK
+
+  @generated @skip @team:DataDog/apm-reliability
+  Scenario: Get a trace by ID returns "Payload Too Large" response
+    Given operation "GetTraceByID" enabled
+    And new "GetTraceByID" request
+    And request contains "trace_id" parameter from "REPLACE.ME"
+    When the request is sent
+    Then the response status is 413 Payload Too Large

features/v2/undo.json

@@ -5290,6 +5290,12 @@
       "type": "safe"
     }
   },
+  "GetPrunedTraceByID": {
+    "tag": "APM Trace",
+    "undo": {
+      "type": "safe"
+    }
+  },
   "QueryScalarData": {
     "tag": "Metrics",
     "undo": {
@@ -8085,6 +8091,12 @@
       "type": "safe"
     }
   },
+  "GetTraceByID": {
+    "tag": "APM Trace",
+    "undo": {
+      "type": "safe"
+    }
+  },
   "GetUsageApplicationSecurityMonitoring": {
     "tag": "Usage Metering",
     "undo": {

lib/datadog_api_client/configuration.rb

@@ -552,6 +552,8 @@ def initialize
             "v2.query_event_filtered_users": false,
             "v2.query_users": false,
             "v2.update_connection": false,
+            "v2.get_pruned_trace_by_id": false,
+            "v2.get_trace_by_id": false,
             "v2.create_scorecard_outcomes_batch": false,
             "v2.list_entity_risk_scores": false,
             "v2.create_incident_service": false,

lib/datadog_api_client/inflector.rb

@@ -1279,6 +1279,8 @@ def overrides
           "v2.apm_resource_stats_data_source" => "ApmResourceStatsDataSource",
           "v2.apm_resource_stats_query" => "ApmResourceStatsQuery",
           "v2.apm_retention_filter_type" => "ApmRetentionFilterType",
+          "v2.apm_span_error_flag" => "APMSpanErrorFlag",
+          "v2.apm_trace_span" => "APMTraceSpan",
           "v2.app_builder_event" => "AppBuilderEvent",
           "v2.app_builder_event_name" => "AppBuilderEventName",
           "v2.app_builder_event_type" => "AppBuilderEventType",
@@ -4732,9 +4734,6 @@ def overrides
           "v2.observability_pipeline_splunk_hec_destination_encoding" => "ObservabilityPipelineSplunkHecDestinationEncoding",
           "v2.observability_pipeline_splunk_hec_destination_token_strategy" => "ObservabilityPipelineSplunkHecDestinationTokenStrategy",
           "v2.observability_pipeline_splunk_hec_destination_type" => "ObservabilityPipelineSplunkHecDestinationType",
-          "v2.observability_pipeline_splunk_hec_metrics_destination" => "ObservabilityPipelineSplunkHecMetricsDestination",
-          "v2.observability_pipeline_splunk_hec_metrics_destination_compression" => "ObservabilityPipelineSplunkHecMetricsDestinationCompression",
-          "v2.observability_pipeline_splunk_hec_metrics_destination_type" => "ObservabilityPipelineSplunkHecMetricsDestinationType",
           "v2.observability_pipeline_splunk_hec_source" => "ObservabilityPipelineSplunkHecSource",
           "v2.observability_pipeline_splunk_hec_source_type" => "ObservabilityPipelineSplunkHecSourceType",
           "v2.observability_pipeline_splunk_hec_source_valid_token" => "ObservabilityPipelineSplunkHecSourceValidToken",
@@ -5141,6 +5140,10 @@ def overrides
           "v2.project_update" => "ProjectUpdate",
           "v2.project_update_attributes" => "ProjectUpdateAttributes",
           "v2.project_update_request" => "ProjectUpdateRequest",
+          "v2.pruned_trace_attributes" => "PrunedTraceAttributes",
+          "v2.pruned_trace_data" => "PrunedTraceData",
+          "v2.pruned_trace_response" => "PrunedTraceResponse",
+          "v2.pruned_trace_type" => "PrunedTraceType",
           "v2.publish_app_response" => "PublishAppResponse",
           "v2.publish_request_type" => "PublishRequestType",
           "v2.put_apps_datastore_item_response_array" => "PutAppsDatastoreItemResponseArray",
@@ -6286,6 +6289,8 @@ def overrides
           "v2.suite_json_patch_request_data_attributes" => "SuiteJsonPatchRequestDataAttributes",
           "v2.suite_json_patch_type" => "SuiteJsonPatchType",
           "v2.suite_search_response_type" => "SuiteSearchResponseType",
+          "v2.summarized_span" => "SummarizedSpan",
+          "v2.summarized_trace" => "SummarizedTrace",
           "v2.suppression_version_history" => "SuppressionVersionHistory",
           "v2.suppression_versions" => "SuppressionVersions",
           "v2.sync_property" => "SyncProperty",
@@ -6694,6 +6699,10 @@ def overrides
           "v2.timeseries_response_attributes" => "TimeseriesResponseAttributes",
           "v2.timeseries_response_series" => "TimeseriesResponseSeries",
           "v2.token_type" => "TokenType",
+          "v2.trace_attributes" => "TraceAttributes",
+          "v2.trace_data" => "TraceData",
+          "v2.trace_response" => "TraceResponse",
+          "v2.trace_type" => "TraceType",
           "v2.trigger" => "Trigger",
           "v2.trigger_attributes" => "TriggerAttributes",
           "v2.trigger_investigation_request" => "TriggerInvestigationRequest",
@@ -7037,6 +7046,7 @@ def overrides
         "v2.api_management_api" => "APIManagementAPI",
         "v2.apm_api" => "APMAPI",
         "v2.apm_retention_filters_api" => "APMRetentionFiltersAPI",
+        "v2.apm_trace_api" => "APMTraceAPI",
         "v2.app_builder_api" => "AppBuilderAPI",
         "v2.application_security_api" => "ApplicationSecurityAPI",
         "v2.audit_api" => "AuditAPI",

lib/datadog_api_client/v2/api/apm_trace_api.rb

@@ -0,0 +1,194 @@
+=begin
+#Datadog API V2 Collection
+
+#Collection of all Datadog Public endpoints.
+
+The version of the OpenAPI document: 1.0
+Contact: support@datadoghq.com
+Generated by: https://github.com/DataDog/datadog-api-client-ruby/tree/master/.generator
+
+ Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0 License.
+ This product includes software developed at Datadog (https://www.datadoghq.com/).
+ Copyright 2020-Present Datadog, Inc.
+
+=end
+
+require 'cgi'
+
+module DatadogAPIClient::V2
+  class APMTraceAPI
+    attr_accessor :api_client
+
+    def initialize(api_client = DatadogAPIClient::APIClient.default)
+      @api_client = api_client
+    end
+
+    # Get a pruned trace by ID.
+    #
+    # @see #get_pruned_trace_by_id_with_http_info
+    def get_pruned_trace_by_id(trace_id, opts = {})
+      data, _status_code, _headers = get_pruned_trace_by_id_with_http_info(trace_id, opts)
+      data
+    end
+
+    # Get a pruned trace by ID.
+    #
+    # Retrieve a pruned, hierarchical view of an APM trace by its trace ID.
+    # The trace is summarized as a tree of spans rooted at the trace root and reduced in size
+    # to keep rendering large traces in the UI practical.
+    # This endpoint is rate limited to `60` requests per minute per organization.
+    #
+    # @param trace_id [String] The trace ID. Accepts either a 32-character hexadecimal string (128-bit trace ID) or a decimal string of up to 39 digits.
+    # @param opts [Hash] the optional parameters
+    # @option opts [Integer] :expand_span_id Span ID to expand and preserve in the pruned tree even when its branch would normally be summarized.
+    # @option opts [Integer] :time_hint Optional Unix time hint, in seconds, used to optimize the lookup of the trace in long-term storage.
+    # @option opts [String] :force_source Force the trace to be loaded from a specific source. When unset, the API picks the source automatically.
+    # @option opts [Array<String>] :include_path Restrict the pruned tree to spans matching the given `key:value` pairs. Values may be passed as repeated query parameters.
+    # @option opts [Array<String>] :tag_include Regex patterns of tag keys whose values must be included in the pruned spans. Values may be passed as repeated query parameters.
+    # @option opts [Array<String>] :tag_exclude Regex patterns of tag keys whose values must be excluded from the pruned spans. Values may be passed as repeated query parameters.
+    # @option opts [Boolean] :only_service_entry_spans When set to `true`, only service entry spans are included in the pruned tree.
+    # @return [Array<(PrunedTraceResponse, Integer, Hash)>] PrunedTraceResponse data, response status code and response headers
+    def get_pruned_trace_by_id_with_http_info(trace_id, opts = {})
+      unstable_enabled = @api_client.config.unstable_operations["v2.get_pruned_trace_by_id".to_sym]
+      if unstable_enabled
+        @api_client.config.logger.warn format("Using unstable operation '%s'", "v2.get_pruned_trace_by_id")
+      else
+        raise DatadogAPIClient::APIError.new(message: format("Unstable operation '%s' is disabled", "v2.get_pruned_trace_by_id"))
+      end
+
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: APMTraceAPI.get_pruned_trace_by_id ...'
+      end
+      # verify the required parameter 'trace_id' is set
+      if @api_client.config.client_side_validation && trace_id.nil?
+        fail ArgumentError, "Missing the required parameter 'trace_id' when calling APMTraceAPI.get_pruned_trace_by_id"
+      end
+      if @api_client.config.client_side_validation && !opts[:'time_hint'].nil? && opts[:'time_hint'] > 2147483647
+        fail ArgumentError, 'invalid value for "opts[:"time_hint"]" when calling APMTraceAPI.get_pruned_trace_by_id, must be smaller than or equal to 2147483647.'
+      end
+      # resource path
+      local_var_path = '/api/v2/pruned_trace/{trace_id}'.sub('{trace_id}', CGI.escape(trace_id.to_s).gsub('%2F', '/'))
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+      query_params[:'expand_span_id'] = opts[:'expand_span_id'] if !opts[:'expand_span_id'].nil?
+      query_params[:'time_hint'] = opts[:'time_hint'] if !opts[:'time_hint'].nil?
+      query_params[:'force_source'] = opts[:'force_source'] if !opts[:'force_source'].nil?
+      query_params[:'include_path'] = @api_client.build_collection_param(opts[:'include_path'], :multi) if !opts[:'include_path'].nil?
+      query_params[:'tag_include'] = @api_client.build_collection_param(opts[:'tag_include'], :multi) if !opts[:'tag_include'].nil?
+      query_params[:'tag_exclude'] = @api_client.build_collection_param(opts[:'tag_exclude'], :multi) if !opts[:'tag_exclude'].nil?
+      query_params[:'only_service_entry_spans'] = opts[:'only_service_entry_spans'] if !opts[:'only_service_entry_spans'].nil?
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json'])
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'PrunedTraceResponse'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || [:apiKeyAuth, :appKeyAuth, :AuthZ]
+
+      new_options = opts.merge(
+        :operation => :get_pruned_trace_by_id,
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type,
+        :api_version => "V2"
+      )
+      new_options[:query_string_normalizer] = HTTParty::Request::NON_RAILS_QUERY_STRING_NORMALIZER
+
+      data, status_code, headers = @api_client.call_api(Net::HTTP::Get, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: APMTraceAPI#get_pruned_trace_by_id\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # Get a trace by ID.
+    #
+    # @see #get_trace_by_id_with_http_info
+    def get_trace_by_id(trace_id, opts = {})
+      data, _status_code, _headers = get_trace_by_id_with_http_info(trace_id, opts)
+      data
+    end
+
+    # Get a trace by ID.
+    #
+    # Retrieve a full APM trace by its trace ID, including every span in the trace.
+    # Traces are returned from live storage when available and fall back to longer-term storage.
+    # This endpoint is rate limited to `60` requests per minute per organization.
+    #
+    # @param trace_id [String] The trace ID. Accepts either a 32-character hexadecimal string (128-bit trace ID) or a decimal string of up to 39 digits.
+    # @param opts [Hash] the optional parameters
+    # @option opts [Array<String>] :include_fields List of span fields to include in the response. When omitted, every available field is returned. Values may be passed as repeated query parameters or as a single comma-separated value.
+    # @return [Array<(TraceResponse, Integer, Hash)>] TraceResponse data, response status code and response headers
+    def get_trace_by_id_with_http_info(trace_id, opts = {})
+      unstable_enabled = @api_client.config.unstable_operations["v2.get_trace_by_id".to_sym]
+      if unstable_enabled
+        @api_client.config.logger.warn format("Using unstable operation '%s'", "v2.get_trace_by_id")
+      else
+        raise DatadogAPIClient::APIError.new(message: format("Unstable operation '%s' is disabled", "v2.get_trace_by_id"))
+      end
+
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: APMTraceAPI.get_trace_by_id ...'
+      end
+      # verify the required parameter 'trace_id' is set
+      if @api_client.config.client_side_validation && trace_id.nil?
+        fail ArgumentError, "Missing the required parameter 'trace_id' when calling APMTraceAPI.get_trace_by_id"
+      end
+      # resource path
+      local_var_path = '/api/v2/trace/{trace_id}'.sub('{trace_id}', CGI.escape(trace_id.to_s).gsub('%2F', '/'))
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+      query_params[:'include_fields'] = @api_client.build_collection_param(opts[:'include_fields'], :multi) if !opts[:'include_fields'].nil?
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json'])
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'TraceResponse'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || [:apiKeyAuth, :appKeyAuth, :AuthZ]
+
+      new_options = opts.merge(
+        :operation => :get_trace_by_id,
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type,
+        :api_version => "V2"
+      )
+      new_options[:query_string_normalizer] = HTTParty::Request::NON_RAILS_QUERY_STRING_NORMALIZER
+
+      data, status_code, headers = @api_client.call_api(Net::HTTP::Get, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: APMTraceAPI#get_trace_by_id\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+  end
+end

lib/datadog_api_client/v2/models/observability_pipeline_splunk_hec_metrics_destination_type.rb → lib/datadog_api_client/v2/models/apm_span_error_flag.rb

@@ -17,10 +17,11 @@
 require 'time'
 
 module DatadogAPIClient::V2
-  # The destination type. Always `splunk_hec_metrics`.
-  class ObservabilityPipelineSplunkHecMetricsDestinationType
+  # Error flag for a span. `1` when the span is in error, `0` otherwise.
+  class APMSpanErrorFlag
     include BaseEnumModel
 
-    SPLUNK_HEC_METRICS = "splunk_hec_metrics".freeze
+    NO_ERROR = 0.freeze
+    ERROR = 1.freeze
   end
 end