packages/synthetics-sdk-api/proto/synthetic_response.proto

// Copyright 2023 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package cloud.monitoring.uptime.synthetic;

message TestResult {
  // The name of the test in this suite, "pings my website". Multiple tests can
  // have the same title & title_path.
  string title = 1;
  // Whether or not the test passed.
  optional bool test_passed = 2;
  // The full path of names from the name of the suite, to the name of the test.
  // Tests may be nested under multiple suites. Eg. ["my suite name", "pings my
  // website", "three times"].
  repeated string title_paths = 3;
  // The start time of the test in iso format.
  string test_start_time = 4;
  // The end time of the test suite in iso format.
  string test_end_time = 5;

  // Information on an error that occurred.
  message TestError {
    // The class of error.
    string error_type = 1;
    // The full error message. Eg. "The url that you are fetching failed DNS
    // lookup".
    string error_message = 2;

    // An individual stack frame that represents a line of code within a file.
    message StackFrame {
      // The name of the function that reported the error.
      string function_name = 1;
      // The name of the file that reported the error.
      string file_path = 2;
      // Line number that reported the error.
      optional int64 line = 3;
      // Column number that reported the error.
      optional int64 column = 4;
    }

    // A list of StackFrame messages that indicate a single trace of code.
    repeated StackFrame stack_frames = 3;
    // The raw stack trace associated with the error.
    string stack_trace = 4;
  }

  // The error that was the result of a test failure.
  TestError test_error = 6;
}

message TestFrameworkResultV1 {
  // The number of total test suites ran.
  optional int64 suite_count = 1;
  // The number of total tests that ran as a part of the suite run.
  optional int64 test_count = 2;
  // The number of total tests that passed as a part of the suite run.
  optional int64 passing_test_count = 3;
  // The number of total tests that failed as a prt of the suite run.
  optional int64 failing_test_count = 4;
  // The number of total tests that remain pending after the suite run.
  optional int64 pending_test_count = 5;
  // A collection of individual test results from a given synthetic's test
  // suite.
  repeated TestResult test_results = 6;
}

message GenericResultV1 {
  // Whether or not the synthetic is considered to have passed.
  optional bool ok = 1;

  message GenericError {
    // The class of error.
    string error_type = 1;
    // The full error message. Eg. "The url that you are fetching failed DNS
    // lookup".
    string error_message = 2;
    // The name of the function where the error occurred.
    string function_name = 3;
    // The name of the file that reported the error.
    string file_path = 4;
    // Line number that reported the error.
    optional int64 line = 5;
    // The raw stack trace that is associated with this error.
    string stack_trace = 6;
  }

  // Error that was associated with this result, causing it to fail.
  GenericError generic_error = 2;
}

// A status to accept. Either a status code class like "2xx", or an
// integer status code like "200".
message ResponseStatusCode {
  // An HTTP status code class.
  enum StatusClass {
    // Default value that matches no status codes.
    STATUS_CLASS_UNSPECIFIED = 0;
    // The class of status codes between 100 and 199.
    STATUS_CLASS_1XX = 100;
    // The class of status codes between 200 and 299.
    STATUS_CLASS_2XX = 200;
    // The class of status codes between 300 and 399.
    STATUS_CLASS_3XX = 300;
    // The class of status codes between 400 and 499.
    STATUS_CLASS_4XX = 400;
    // The class of status codes between 500 and 599.
    STATUS_CLASS_5XX = 500;
    // The class of all status codes.
    STATUS_CLASS_ANY = 1000;
  }
  // Either a specific value or a class of status codes.
  oneof status_code {
    // A status code to accept.
    int32 status_value = 1;
    // A class of status codes to accept.
    StatusClass status_class = 2;
  }
}

// Information on an error that occurred.
message BaseError {
  // The name of the error.
  string error_type = 1;
  // The full error message.
  string error_message = 2;
}

// Aggregate and individual results of a Broken Link Synthetic execution
message BrokenLinksResultV1 {
  // the total number of links checked as part of the execution
  optional int64 link_count = 1;
  // the total number of links that passed as part of the execution
  optional int64 passing_link_count = 2;
  // the total number of links that failed
  optional int64 failing_link_count = 3;
  // the total number of links that count not be reached
  optional int64 unreachable_count = 4;
  // the total number of links that returned 2xx status codes
  optional int64 status2xx_count = 5;
  // the total number of links that returned 3xx status codes
  optional int64 status3xx_count = 6;
  // the total number of links that returned 4xx status codes
  optional int64 status4xx_count = 7;
  // the total number of links that returned 5xx status codes
  optional int64 status5xx_count = 8;

  message BrokenLinkCheckerOptions {
    // Origin uri from which to scrape all other links, this is the only
    // required field.
    string origin_uri = 1;
    // Number of links to follow, default 50.
    optional int64 link_limit = 2;
    // HTML elements to scrape from origin_uri, default 'a'.
    string query_selector_all = 3;
    // Attributes to scrape from queried HTML elements, default ['href'].
    repeated string get_attributes = 4;

    // Possible orders for checking links that have been scraped.
    enum LinkOrder {
      // Default value that indicates no order.
      LINK_ORDER_UNSPECIFIED = 0;
      // First "n" number of links scraped.
      FIRST_N = 1;
      // Random selection of links scraped.
      RANDOM = 2;
    }

    // order to check links scraped
    LinkOrder link_order = 5;  // default FIRST_N
    // Maximum amount of time to wait for HTTP response to complete per link,
    // default 30000 milliseconds.
    optional int64 link_timeout_millis = 6;
    // Maximum number of times to retry a link that does not return the
    // “expected_status_code”.
    optional int64 max_retries = 7;

    reserved 8;
    reserved "max_redirects";

    // HTML element to wait for before scraping links on origin_uri.
    // Method documentation:
    // https://pptr.dev/api/puppeteer.page.waitforselector. Type documentation:
    // https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors
    string wait_for_selector = 9;

    // Individual link options.
    message PerLinkOption {
      // The expected status code or class.
      ResponseStatusCode expected_status_code = 1;
      // Maximum amount of time to wait for HTTP response to complete, for
      // the given specified link passed in "per_link_options" map.
      optional int64 link_timeout_millis = 2;
    }

    // individual link options, default None. string must be formatted as a
    // fully qualified url
    map<string, PerLinkOption> per_link_options = 10;
    // Timeout set for the entire Synthetic Monitor, default 60000 milliseconds
    optional int64 total_synthetic_timeout_millis = 11;

    // Required options for broken link checker screenshot capability.
    message ScreenshotOptions {
      // Input bucket or folder provided by the user.
      string storage_location = 1;

      enum CaptureCondition {
        NONE = 0;
        FAILING = 1;
        ALL = 2;
      }

      // Controls when to capture screenshots during broken link checks, default
      // is FAILING.
      CaptureCondition capture_condition = 2;
    }

    // Screenshot options, default to 'FAILING' and synthetic wide bucket.
    ScreenshotOptions screenshot_options = 12;
  }

  // Options set for broken link synthetic.
  BrokenLinkCheckerOptions options = 9;

  // Result of a single link checked / network request
  message SyntheticLinkResult {
    // Whether or not the status code is the same as "expected_status_code".
    optional bool link_passed = 1;
    // The expected status code or status class.
    ResponseStatusCode expected_status_code = 2;
    // Source_uri from which the target_uri is navigated from.
    string source_uri = 3;
    // Target_uri navigated to from the source_uri.
    string target_uri = 4;
    // Anchor text on the source URI.
    string anchor_text = 5;
    // HTML element from which target_uri was scraped.
    string html_element = 6;
    // Status code returned by the target_uri.
    optional int64 status_code = 7;
    // 'BrokenLinksSynthetic_IncorrectStatusCode' if the expected and actual
    // status codes differ. Otherwise, the class of the error thrown, eg
    // 'connectionaborted', docs: https://pptr.dev/api/puppeteer.errorcode.
    string error_type = 8;
    // Error Message, if any
    string error_message = 9;
    // The start time of the link navigation in iso format.
    string link_start_time = 10;
    // The end time of the link navigation in iso format.
    string link_end_time = 11;
    // These fields only apply to the origin link.
    optional bool is_origin = 12;

    // Result of Screenshot Upload to GCS.
    message ScreenshotOutput {
      // Name of screenshot_file.
      string screenshot_file = 1;

      // Error that occurred throughout screenshot workflow.
      BaseError screenshot_error = 2;
    }

    // Output of screenshot upload attempt.
    ScreenshotOutput screenshot_output = 13;
  }

  // link result for origin_uri.
  SyntheticLinkResult origin_link_result = 10;
  // link results for all scraped and followed links.
  repeated SyntheticLinkResult followed_link_results = 11;

  // Path to the Cloud Storage folder where all artifacts (e.g. screenshots)
  // will be stored for this execution. e.g.
  // gs://<my_bucket_name/check-id-123/2024-01-01/123exec_id123/
  string execution_data_storage_path = 12;

  // Errors associated with the broken link checker execution.
  repeated BaseError errors = 13;
}

message SyntheticResult {
  oneof result {
    TestFrameworkResultV1 synthetic_test_framework_result_v1 = 1;
    GenericResultV1 synthetic_generic_result_v1 = 2;
    BrokenLinksResultV1 synthetic_broken_links_result_v1 = 3;
  }

  // Used to determine information about the runtime environment that the
  // synthetic is running in, such as K_SERVICE, and K_REVISION for cloud run,
  // SYNTHETIC_SDK_NPM_PACKAGE_VERSION for nodejs package.
  map<string, string> runtime_metadata = 4;
  // The start time of the synthetic in iso format.
  string start_time = 5;
  // The end time of the synthetic in iso format.
  string end_time = 6;
}