path: root/proto/icing/proto/logging.proto

// Copyright 2019 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
//
//      http://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 = "proto2";

package icing.lib;

import "icing/proto/scoring.proto";

option java_package = "com.google.android.icing.proto";
option java_multiple_files = true;
option objc_class_prefix = "ICNG";

// Stats of the top-level function IcingSearchEngine::Initialize().
// Next tag: 14
message InitializeStatsProto {
  // Overall time used for the function call.
  optional int32 latency_ms = 1;

  // The cause of IcingSearchEngine recovering from a previous bad state during
  // initialization.
  enum RecoveryCause {
    // No recovery happened.
    NONE = 0;

    // Data loss in ground truth.
    DATA_LOSS = 1;

    // Data in index is inconsistent with ground truth.
    INCONSISTENT_WITH_GROUND_TRUTH = 2;

    // Changes were made to the schema, but possibly not fully applied to the
    // document store and the index - requiring a recovery.
    SCHEMA_CHANGES_OUT_OF_SYNC = 3;

    // Random I/O errors.
    IO_ERROR = 4;

    // The document log is using legacy format.
    LEGACY_DOCUMENT_LOG_FORMAT = 5;

    // The current code version is different from existing data version.
    VERSION_CHANGED = 6;
  }

  // Possible recovery causes for document store:
  // - DATA_LOSS
  // - SCHEMA_CHANGES_OUT_OF_SYNC
  // - IO_ERROR
  optional RecoveryCause document_store_recovery_cause = 2;

  // Possible recovery causes for index:
  // - INCONSISTENT_WITH_GROUND_TRUTH
  // - SCHEMA_CHANGES_OUT_OF_SYNC
  // - IO_ERROR
  optional RecoveryCause index_restoration_cause = 3;

  // Possible recovery causes for index:
  // - IO_ERROR
  optional RecoveryCause schema_store_recovery_cause = 4;

  // Time used to recover the document store.
  optional int32 document_store_recovery_latency_ms = 5;

  // Time used to restore the index.
  optional int32 index_restoration_latency_ms = 6;

  // Time used to restore the index.
  optional int32 schema_store_recovery_latency_ms = 7;

  // Status regarding how much data is lost during the initialization.
  enum DocumentStoreDataStatus {
    // Document store is successfully initialized or fully recovered.
    NO_DATA_LOSS = 0;

    // Ground truth data is partially lost.
    PARTIAL_LOSS = 1;

    // Ground truth data is completely lost.
    COMPLETE_LOSS = 2;
  }
  optional DocumentStoreDataStatus document_store_data_status = 8;

  // Number of documents currently in document store. Those may
  // include alive, deleted, and expired documents.
  optional int32 num_documents = 9;

  // Number of schema types currently in schema store.
  optional int32 num_schema_types = 10;

  // Number of consecutive initialization failures that immediately preceded
  // this initialization.
  optional int32 num_previous_init_failures = 11;

  // Possible recovery causes for integer index:
  // - INCONSISTENT_WITH_GROUND_TRUTH
  // - SCHEMA_CHANGES_OUT_OF_SYNC
  // - IO_ERROR
  optional RecoveryCause integer_index_restoration_cause = 12;

  // Possible recovery causes for qualified id join index:
  // - INCONSISTENT_WITH_GROUND_TRUTH
  // - SCHEMA_CHANGES_OUT_OF_SYNC
  // - IO_ERROR
  optional RecoveryCause qualified_id_join_index_restoration_cause = 13;
}

// Stats of the top-level function IcingSearchEngine::Put().
// Next tag: 10
message PutDocumentStatsProto {
  // Overall time used for the function call.
  optional int32 latency_ms = 1;

  // Time used to store the document.
  optional int32 document_store_latency_ms = 2;

  // Time used to index the document.
  optional int32 index_latency_ms = 3;

  // Time used to merge the indices.
  optional int32 index_merge_latency_ms = 4;

  // Document size in bytes.
  optional int32 document_size = 5;

  message TokenizationStats {
    // Number of tokens added to the index.
    optional int32 num_tokens_indexed = 1;

    reserved 2;
  }
  optional TokenizationStats tokenization_stats = 6;

  // Time used to index all indexable string terms in the document. It does not
  // include the time to merge indices.
  optional int32 term_index_latency_ms = 7;

  // Time used to index all indexable integers in the document.
  optional int32 integer_index_latency_ms = 8;

  // Time used to index all qualified id join strings in the document.
  optional int32 qualified_id_join_index_latency_ms = 9;
}

// Stats of the top-level function IcingSearchEngine::Search() and
// IcingSearchEngine::GetNextPage().
// Next tag: 23
message QueryStatsProto {
  // The UTF-8 length of the query string
  optional int32 query_length = 16;

  // Number of terms in the query string.
  optional int32 num_terms = 1;

  // Number of namespaces filtered.
  optional int32 num_namespaces_filtered = 2;

  // Number of schema types filtered.
  optional int32 num_schema_types_filtered = 3;

  // Strategy of scoring and ranking.
  optional ScoringSpecProto.RankingStrategy.Code ranking_strategy = 4;

  // Whether the function call is querying the first page. If it’s
  // not, Icing will fetch the results from cache so that some steps
  // may be skipped.
  optional bool is_first_page = 5;

  // The requested number of results in one page.
  optional int32 requested_page_size = 6;

  // The actual number of results returned in the current page.
  optional int32 num_results_returned_current_page = 7;

  // Number of documents scored.
  optional int32 num_documents_scored = 8;

  // How many of the results in the page returned were snippeted.
  optional int32 num_results_with_snippets = 15;

  // Overall time used for the function call.
  optional int32 latency_ms = 10;

  // Time used to parse the query, including 2 parts: tokenizing and
  // transforming tokens into an iterator tree.
  optional int32 parse_query_latency_ms = 11;

  // Time used to score the raw results.
  optional int32 scoring_latency_ms = 12;

  // Time used to rank the scored results.
  optional int32 ranking_latency_ms = 13;

  // Time used to fetch the document protos. Note that it includes the
  // time to snippet if ‘has_snippets’ is true.
  optional int32 document_retrieval_latency_ms = 14;

  // Time passed while waiting to acquire the lock before query execution.
  optional int32 lock_acquisition_latency_ms = 17;

  // Timestamp taken just before sending proto across the JNI boundary from
  // native to java side.
  optional int64 native_to_java_start_timestamp_ms = 18;

  // Time used to send protos across the JNI boundary from java to native side.
  optional int32 java_to_native_jni_latency_ms = 19;

  // Time used to send protos across the JNI boundary from native to java side.
  optional int32 native_to_java_jni_latency_ms = 20;

  // The native latency due to the join operation.
  optional int32 join_latency_ms = 21;

  // Number of documents scored.
  optional int32 num_joined_results_returned_current_page = 22;

  reserved 9;
}

// Stats of the top-level functions IcingSearchEngine::Delete,
// IcingSearchEngine::DeleteByNamespace, IcingSearchEngine::DeleteBySchemaType.
// Next tag: 4
message DeleteStatsProto {
  // Overall time used for the function call.
  optional int32 latency_ms = 1;

  message DeleteType {
    enum Code {
      // Default. Should never be used.
      UNKNOWN = 0;

      // Delete one document.
      SINGLE = 1;

      // Delete by query. This value is deprecated.
      // IcingSearchEngine::DeleteByQuery will return a DeleteByQueryStatsProto
      // rather than a DeleteStatsProto.
      DEPRECATED_QUERY = 2 [deprecated = true];

      // Delete by namespace.
      NAMESPACE = 3;

      // Delete by schema type.
      SCHEMA_TYPE = 4;
    }
  }
  optional DeleteType.Code delete_type = 2;

  // Number of documents deleted by this call.
  optional int32 num_documents_deleted = 3;
}

// Stats of the top-level functions IcingSearchEngine::DeleteByQuery.
// Next tag: 9
message DeleteByQueryStatsProto {
  // Overall time used for the function call.
  optional int32 latency_ms = 1;

  // Number of documents deleted by this call.
  optional int32 num_documents_deleted = 2;

  // The UTF-8 length of the query string
  optional int32 query_length = 3;

  // Number of terms in the query string.
  optional int32 num_terms = 4;

  // Number of namespaces filtered.
  optional int32 num_namespaces_filtered = 5;

  // Number of schema types filtered.
  optional int32 num_schema_types_filtered = 6;

  // Time used to parse the query, including 2 parts: tokenizing and
  // transforming tokens into an iterator tree.
  optional int32 parse_query_latency_ms = 7;

  // Time used to delete each document.
  optional int32 document_removal_latency_ms = 8;
}