/**
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you 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.
 */

/**
 * A Span is our basic unit of tracing. It tracks the critical points
 * of a single RPC call and records other call meta-data. It also
 * allows arbitrary string annotations. Both the client and server create
 * Span objects, each of which is populated with half of the relevant event
 * data. They share a span ID, which allows us to merge them into one complete
 * span later on.
 */
@namespace("org.apache.avro.ipc.trace")

protocol AvroTrace {
  enum SpanEvent { SERVER_RECV, SERVER_SEND, CLIENT_RECV, CLIENT_SEND }

  fixed ID(8);

  record TimestampedEvent {
    long timeStamp; // Unix time, in nanoseconds
    union { SpanEvent, string} event;
  }

  /**
   * An individual span is the basic unit of testing.
   * The record is used by both \"client\" and \"server\".
   */
  record Span {
    ID  traceID;  // ID shared by all Spans in a given trace
    ID spanID;    // Random ID for this Span
    union { ID, null } parentSpanID; // Parent Span ID (null if root Span)
    string messageName;       // Function call represented
    long requestPayloadSize;  // Size (bytes) of the request
    long responsePayloadSize; // Size (byts) of the response
    union { string, null} requestorHostname; // Hostname of requestor
//    int requestorPort;     // Port of the requestor (currently unused)
    union { string, null } responderHostname; // Hostname of the responder
//    int responderPort;     // Port of the responder (currently unused)
    array<TimestampedEvent> events;  // List of critical events
    boolean complete; // Whether includes data from both sides
  }

  /**
   * Get all spans stored on this host.
   */
  array<Span> getAllSpans();

  /**
   * Get spans occuring between start and end. Each is a unix timestamp
   * in nanosecond units (for consistency with TimestampedEvent).
   */
  array<Span> getSpansInRange(long start, long end);
}
