//-----------------------------------------------------------------------------
// <copyright file="IAWSXRayRecorder.cs" company="Amazon.com">
//      Copyright 2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
//
//      Licensed under the Apache License, Version 2.0 (the "License").
//      You may not use this file except in compliance with the License.
//      A copy of the License is located at
//
//      http://aws.amazon.com/apache2.0
//
//      or in the "license" file accompanying this file. This file 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.
// </copyright>
//-----------------------------------------------------------------------------

using System;
using System.Collections.Generic;
using Amazon.XRay.Recorder.Core.Sampling;
using Amazon.XRay.Recorder.Core.Strategies;
using System.Threading.Tasks;
using Amazon.XRay.Recorder.Core.Exceptions;
using Amazon.XRay.Recorder.Core.Internal.Context;
using Amazon.XRay.Recorder.Core.Internal.Emitters;

namespace Amazon.XRay.Recorder.Core
{
    /// <summary>
    /// Interface to record tracing information for AWS X-Ray
    /// </summary>
    public interface IAWSXRayRecorder : IDisposable
    {
        /// <summary>
        /// Gets or sets origin service
        /// </summary>
        string Origin { get; set; }

        /// <summary>
        /// Gets or sets the sampling strategy
        /// </summary>
        ISamplingStrategy SamplingStrategy { get; set; }

        /// <summary>
        /// Get or sets the streaming strategy
        /// </summary>
        IStreamingStrategy StreamingStrategy { get; set; }

        /// <summary>
        /// Gets or sets the context missing strategy.
        /// </summary>
        ContextMissingStrategy ContextMissingStrategy { get; set; }

        /// <summary>
        /// Gets the runtime context which is generated by plugins.
        /// </summary>
        IDictionary<string, object> RuntimeContext { get; }

        /// <summary>
        /// Defines exception serialization stategy to process recorded exceptions. <see cref="Strategies.ExceptionSerializationStrategy"/>
        /// </summary>
        ExceptionSerializationStrategy ExceptionSerializationStrategy { get; set; }
        /// <summary>
        /// Instance of <see cref="ITraceContext"/>, used to store segment/subsegment.
        /// </summary>
        ITraceContext TraceContext { get; set; }

        /// <summary>
        /// Emitter used to send Traces.
        /// </summary>
        ISegmentEmitter Emitter { get; set; }

        /// <summary>
        /// Begin a tracing segment. A new tracing segment will be created and started.
        /// </summary>
        /// <param name="name">The name of the segment</param>
        /// <param name="traceId">Trace id of the segment</param>
        /// <param name="parentId">Unique id of the upstream remote segment or subsegment where the downstream call originated from.</param>
        /// <param name="samplingResponse">Instance  of <see cref="SamplingResponse"/>, contains sampling decision for the segment from upstream service. If not passed, sampling decision is made based on <see cref="SamplingStrategy"/> set with the recorder instance.</param>
        /// <param name="timestamp">If not null, sets the start time for the segment else current time is set.</param>
        /// <exception cref="ArgumentNullException">The argument has a null value.</exception>
        void BeginSegment(string name, string traceId = null, string parentId = null, SamplingResponse samplingResponse = null, DateTime? timestamp = null);

        /// <summary>
        /// End tracing of a given segment.
        /// </summary>
        /// <param name="timestamp">If not null, set as endtime for the current segment.</param>
        /// <exception cref="EntityNotAvailableException">Entity is not available in trace context.</exception>
        void EndSegment(DateTime? timestamp = null);

        /// <summary>
        /// Start a subsegment with a given name and optional creation timestamp
        /// </summary>
        /// <param name="name">Name of the subsegment</param>
        /// <param name="timestamp">Sets the start time for the subsegment</param>
        void BeginSubsegment(string name, DateTime? timestamp = null);

        /// <summary>
        /// Start a subsegment with a given name
        /// This subsegment will not emit and its trace context will have Sampled=0
        /// </summary>
        /// <param name="name">Name of the subsegment</param>
        void BeginSubsegmentWithoutSampling(string name);

        /// <summary>
        /// End a subsegment
        /// </summary>
        /// <param name="timestamp">Sets the end time for the subsegment</param>
        void EndSubsegment(DateTime? timestamp = null);

        /// <summary>
        /// Set namespace to current segment
        /// </summary>
        /// <param name="value">The value of the namespace</param>
        void SetNamespace(string value);

        /// <summary>
        /// Adds the specified key and value as annotation to current segment
        /// </summary>
        /// <param name="key">The key of the annotation to add</param>
        /// <param name="value">The value of the annotation to add</param>
        void AddAnnotation(string key, object value);

        /// <summary>
        /// Mark the current segment as fault.
        /// </summary>
        void MarkFault();

        /// <summary>
        /// Mark the current segment as error.
        /// </summary>
        void MarkError();

        /// <summary>
        /// Add the exception to current segment
        /// </summary>
        /// <param name="ex">The exception to be added.</param>
        void AddException(Exception ex);

        /// <summary>
        /// Trace a given method with return value. 
        /// </summary>
        /// <typeparam name="TResult">The type of the return value of the method that this delegate encapsulates</typeparam>
        /// <param name="name">The name of the trace subsegment for the method</param>
        /// <param name="method">The method to be traced</param>
        /// <returns>The return value of the given method</returns>
        TResult TraceMethod<TResult>(string name, Func<TResult> method);

        /// <summary>
        /// Trace a given method returns void.
        /// </summary>
        /// <param name="name">The name of the trace subsegment for the method</param>
        /// <param name="method">The method to be traced</param>
        void TraceMethod(string name, Action method);

        /// <summary>
        /// Trace a given asynchronous function with return value. A subsegment will be created for this method.
        /// Any exception thrown by the method will be captured.
        /// </summary>
        /// <typeparam name="TResult">The type of the return value of the method that this delegate encapsulates</typeparam>
        /// <param name="name">The name of the trace subsegment for the method</param>
        /// <param name="method">The method to be traced</param>
        /// <returns>The return value of the given method</returns>
        Task<TResult> TraceMethodAsync<TResult>(string name, Func<Task<TResult>> method);

        /// <summary>
        /// Trace a given asynchronous method that returns no value.  A subsegment will be created for this method.
        /// Any exception thrown by the method will be captured.
        /// </summary>
        /// <param name="name">The name of the trace subsegment for the method</param>
        /// <param name="method">The method to be traced</param>
        Task TraceMethodAsync(string name, Func<Task> method);

        /// <summary>
        /// Adds the specified key and value as http information to current segment
        /// </summary>
        /// <param name="key">The key of the http information to add</param>
        /// <param name="value">The value of the http information to add</param>
        void AddHttpInformation(string key, object value);

        /// <summary>
        /// Mark the current segment as being throttled.
        /// </summary>
        void MarkThrottle();

        /// <summary>
        /// Add a precursor id.
        /// </summary>
        /// <param name="precursorId">The precursor id to be added.</param>
        void AddPrecursorId(string precursorId);

        /// <summary>
        /// Add the specified key and value as SQL information to current segment
        /// </summary>
        /// <param name="key">The key of the SQL information</param>
        /// <param name="value">The value of the SQL information</param>
        void AddSqlInformation(string key, string value);

        /// <summary>
        /// Adds the specified key and value to metadata under default namespace.
        /// </summary>
        /// <param name="key">The key.</param>
        /// <param name="value">The value.</param>
        void AddMetadata(string key, object value);

        /// <summary>
        /// Adds the specified key and value to metadata with given namespace.
        /// </summary>
        /// <param name="nameSpace">The namespace.</param>
        /// <param name="key">The key.</param>
        /// <param name="value">The value.</param>
        void AddMetadata(string nameSpace, string key, object value);

        /// <summary>
        /// Sets the daemon address.
        /// The daemon address should be in format "IPAddress:Port", i.e. "127.0.0.1:2000".
        /// If environment variable is set to specific daemon address, the call to this method
        /// will be ignored.
        /// </summary>
        /// <param name="daemonAddress">The daemon address.</param>
        void SetDaemonAddress(string daemonAddress);
    }
}