Trace (etrace-agent 0.0.2 API)

java.lang.Object
- io.etrace.agent.Trace

```
public class Trace
extends Object
```
The main api of trace.
1. wiki link: http://wiki.ele.to:8090/pages/viewpage.action?pageId=47703803 2. add javadoc on each api.
Limitation: Considering the trade-off between convenience of Trace api and the resource usage of agent application, there are some default limitation on the length of names, the size of tags, the number of one Transaction's children and etc. For example, if the length or the size exceeds the threshold, the excessive part will be ignored. Finally, if you encounter any problems, send email to arch.etrace@ele.me for help.
As for string length, when the size more than max size,it will be String.substring(0, maxSize). -- Trace: ---- type: 256 char ---- name: 512 char ---- status: 64 char ---- data: 2 * 1024 char(default), adjustable ---- tag name: 64 char ---- tag value: 256 char(default), adjustable ---- tag size: 12(default), adjustable
-- Metric: ---- name: 512 char ---- tag name: 64 char(default), adjustable ---- tag value: 256 char(default) , adjustable ---- tag size: 8(default), adjustable
-- Redis size: ---- 500 redis("{url}{command}") every Transaction context
-- Metric Name: ---- 100 (default, adjustable) metric name every two seconds
============================================================================================================
The Hierarchical Relation between service and service, thread and thread, service and thread , etc.
First, get the requestId (getCurrentRequestId() ) and rpcId (nextLocalRpcId()nextRemoteRpcId()) after creating a new Transaction: Transaction t = Trace.newTransaction("Type", "Name"); String requestId = Trace.getCurrentRequestId(); String rpcId = Trace.nextLocalRpcId(); //local thread //String rpcId = Trace.nextRemoteRpcId() //remote server

Second, transfer the requestId and rpcId to next service or thread. Then, in the next service or thread, use continueTrace(String, String) to bind it : Trace.continueTrace(requestId, rpcId);
It succeeds in creating a Transaction, and you can get the hierarchical relation information in ETrace.
============================================================================================================
Redis stats: -- counter of redis calls = (succeedCount + failCount) -- cost time of redis calls = (durationSucceedSum + durationFailSum) -- maxDuration, minDuration: the max(or min) cost time of redis calls
If fail to get the response, these values below are (-1) and the default is also (-1). -- responseCount, responseSizeSum, maxResponseSize, minResponseSize -- hitCount : counter of response where the response hit is true

Method Summary

All Methods Static Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`static void`	`clean()` Clear all trace stacks and context in the local thread.
`static void`	`continueTrace(String requestId, String rpcId)` Bind the requestId and rpcId of previous service or thread to the present More details, please see the Hierarchical Relation : `Trace`
`static TraceContext`	`exportContext()`
`static int`	`getCallStackProducerQueueSize()`
`static String`	`getClientAppId()` get the appId from local thread context if local thread context is null (sometimes it means you don't have any Transaction in your context), it is going to return "unknown"
`static String`	`getCurrentRequestId()` Get the current request id the rule of request id : {serviceName}^^{random long or uuid}\|{timestamp} serviceName = serviceName (first) or appId (second) or unknown (last) such as : arch .etrace^^-1018579420457251359\|1503388031849 more detail about RpcId
`static String`	`getCurrentRpcId()` 已修复成 getRpcId()
`static String`	`getCurrentRpcIdAndCurrentCall()` return rpcId + "." + currentCall deprecated.
`static String`	`getCurrentRpcIdWithAppId()`
`static String`	`getRpcId()` more detail about RpcId, refer to ：http://wiki.ele.to:8090/pages/viewpage.action?pageId=62202413 "RequestId与RpcId说明"
`static CallstackStats`	`getStats()`
`static int`	`getTCPMessageSenderQueueSize()`
`static boolean`	`hasContext()` Whether there is any Context in the local thread
`static boolean`	`hasTransaction()` Whether there is any Transaction that hasn't completed in the local thread context.
`static void`	`importContext(TraceContext context)`
`static boolean`	`isImportContext()`
`static void`	`logError(String message, Throwable throwable)` create a new event, then set the message and the throwable stack information, finally complete.
`static void`	`logError(String message, Throwable throwable, Map<String,String> tags)`
`static void`	`logError(Throwable throwable)` create a new event, then set the throwable stack information to data, finally complete.
`static void`	`logError(Throwable throwable, Map<String,String> tags)`
`static void`	`logEvent(String type, String name)` create a event that the status is Constants.SUCCESS, and without setting data or tags.
`static void`	`logEvent(String type, String name, String status)`
`static void`	`logEvent(String type, String name, String status, Map<String,String> tags)`
`static void`	`logEvent(String type, String name, String status, String data, Map<String,String> tags)`
`static void`	`logHeartbeat(String type, String name, String status, String data, Map<String,String> tags)`
`static Counter`	`newCounter(String name)` Counter counter = Trace.newCounter("metric-name"); //create a new Counter counter.addTag("key-1", "value-1"); // add tag counter.once(); // set value=1, when call once, the Counter finishes, refer to: `Counter.once()`
`static Event`	`newEvent(String type, String name)` Deprecated.
`static Gauge`	`newGauge(String name)` Gauge gauge = Trace.newGauge("metric-name"); //create a new Gauge gauge.addTag("key-1", "value-1").addTag("key-2", "value-2"); //add tag gauge.value(200); //set value=200, when call value(200), the Gauge finishes, refer to : `Gauge.value(double)`
`static Payload`	`newPayload(String name)` Payload payload = Trace.newPayload("metric-name"); //create a new Payload, the time point is (System.currentTimeMillis()) payload.addTag("key-1", "value-1").addTag("key-2", "value-2"); //add tag payload.value(1000); //set value = 1000, count = 1, and the Payload finishes, refer to : `Payload.value(long)`
`static Timer`	`newTimer(String name)` The timer doesn't support the quantile(upper_85,upper_90 etc.), but another metric type : Histogram do.
`static Transaction`	`newTransaction(String type, String name)` Transaction t = Trace.newTransaction("Type", "Name"); try { t.addTag("key","value"); // add tag //Do business logic t.setStatus(Constants.SUCCESS); // please set status before return, and means it succeed to do the task.
`static String`	`nextLocalRpcId()` get next thread rpc id rpc id rule : `getRpcId()`
`static String`	`nextRemoteRpcId()` get next remote rpc id the rule of rpc id : `getRpcId()`
`static void`	`redis(String url, String command, long duration, boolean succeed)` Deprecated.
`static void`	`redis(String url, String command, long duration, boolean succeed, RedisResponse response)` Deprecated.
`static void`	`redis(String url, String command, long duration, boolean succeed, RedisResponse[] responses)` Deprecated.
`static void`	`redis(String url, String command, long duration, boolean succeed, RedisResponse[] responses, String redisType)` Deprecated.
`static void`	`redis(String url, String command, long duration, boolean succeed, RedisResponse response, String redisType)` Deprecated.
`static void`	`redis(String url, String command, long duration, boolean succeed, String redisType)` Deprecated.
`static void`	`removeContext()` remove the local thread context if it exists.
`static void`	`shutdownTrace()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - shutdownTrace
```
public static void shutdownTrace()
```
  - getStats
```
public static CallstackStats getStats()
```
  - getCallStackProducerQueueSize
```
public static int getCallStackProducerQueueSize()
```
  - getTCPMessageSenderQueueSize
```
public static int getTCPMessageSenderQueueSize()
```
  - newEvent
```
@Deprecated
public static Event newEvent(String type,
                                         String name)
```
    Deprecated.
    
    Event event = Trace.newEvent("type", "name"); // create a new event try{ event.setData("data"); // set data event.addTag("key","value"); // add tag event.setStatus(Constants.SUCCESS); //set status }finally { event.complete(); // complete is necessary, otherwise the event is invalid. }
    
    Parameters:
    
    type - event type
    
    name - event name
    
    Returns:
    
    me.ele.arch.etrace.common.modal.Event
    废弃。不如使用logEvent方便。
  - logEvent
```
public static void logEvent(String type,
                            String name)
```
    create a event that the status is Constants.SUCCESS, and without setting data or tags.
    
    Parameters:
    
    type - the event type
    
    name - the event name
  - logEvent
```
public static void logEvent(String type,
                            String name,
                            String status)
```
    Parameters:
    
    type - the event type
    
    name - the event name
    
    status - the event status
  - logEvent
```
public static void logEvent(String type,
                            String name,
                            String status,
                            Map<String,String> tags)
```
    Parameters:
    
    type - the event type
    
    name - the event name
    
    status - the event status
    
    tags - the tags
  - logEvent
```
public static void logEvent(String type,
                            String name,
                            String status,
                            String data,
                            Map<String,String> tags)
```
    Parameters:
    
    type - the event type
    
    name - the event name
    
    status - the event status
    
    data - the data
    
    tags - the tags
  - logError
```
public static void logError(Throwable throwable)
```
    create a new event, then set the throwable stack information to data, finally complete. it calls Trace.logError(null, throwable), please look at the logError(String, Throwable)
    
    Parameters:
    
    throwable - the error Throwable
  - logError
```
public static void logError(Throwable throwable,
                            Map<String,String> tags)
```
  - logError
```
public static void logError(String message,
                            Throwable throwable)
```
    create a new event, then set the message and the throwable stack information, finally complete.
    -- Event Type: if throwable instanceof me.ele.contract.exception.ServiceException : type = "BusinessException" else if throwable instanceof java.lang.Error : type = "Error" else if throwable instanceof java.lang.RuntimeException : type = "RuntimeException" else type = "Exception"
    -- Event Name: name = throwable.getClass().getName()
    -- Status: status = "ERROR"
    
    Parameters:
    
    message - the message to describe something
    
    throwable - exception
  - logError
```
public static void logError(String message,
                            Throwable throwable,
                            Map<String,String> tags)
```
  - newTransaction
```
public static Transaction newTransaction(String type,
                                         String name)
```
    Transaction t = Trace.newTransaction("Type", "Name"); try { t.addTag("key","value"); // add tag //Do business logic t.setStatus(Constants.SUCCESS); // please set status before return, and means it succeed to do the task. } catch (InterruptedException e) { Trace.logError(e); // create a event to record the error t.setStatus(e); // record transaction error status, means it catches the error. } finally { t.complete(); // It must complete finally. }
    
    Parameters:
    
    type - the type
    
    name - the name
    
    Returns:
    
    me.ele.arch.etrace.common.modal.Transaction
  - hasTransaction
```
public static boolean hasTransaction()
```
    Whether there is any Transaction that hasn't completed in the local thread context.
    
    Returns:
    
    boolean
  - clean
```
public static void clean()
```
    Clear all trace stacks and context in the local thread. In only want to clear context, call removeContext()
  - hasContext
```
public static boolean hasContext()
```
    Whether there is any Context in the local thread
    
    Returns:
    
    boolean
  - continueTrace
```
public static void continueTrace(String requestId,
                                 String rpcId)
```
    Bind the requestId and rpcId of previous service or thread to the present More details, please see the Hierarchical Relation : Trace
    
    Parameters:
    
    requestId - requestId
    
    rpcId - rpcId
  - getCurrentRequestId
```
public static String getCurrentRequestId()
```
    Get the current request id the rule of request id : {serviceName}^^{random long or uuid}|{timestamp} serviceName = serviceName (first) or appId (second) or unknown (last) such as : arch .etrace^^-1018579420457251359|1503388031849 more detail about RpcId
    
    Returns:
    
    String
  - getRpcId
```
public static String getRpcId()
```
    more detail about RpcId, refer to ：http://wiki.ele.to:8090/pages/viewpage.action?pageId=62202413 "RequestId与RpcId说明"
    return rpcId
  - getCurrentRpcId
```
public static String getCurrentRpcId()
```
    已修复成 getRpcId()
    
    Returns:
    
    String
  - getCurrentRpcIdAndCurrentCall
```
public static String getCurrentRpcIdAndCurrentCall()
```
    return rpcId + "." + currentCall deprecated. use getRpcId() instead. more detail about RpcId, refer to
    在某个场景：前文调用了nextRemoteRpcId()后，再调用getCurrentRpcId()返回的rpcId是下一层次的（即与Remote Call同级），实际上应是当前层次。可能会造成显式传递RpcId时，层次错误。另一个api: getRpcId()修复了这个问题。
  - removeContext
```
public static void removeContext()
```
    remove the local thread context if it exists.
  - getCurrentRpcIdWithAppId
```
public static String getCurrentRpcIdWithAppId()
```
  - nextRemoteRpcId
```
public static String nextRemoteRpcId()
```
    get next remote rpc id the rule of rpc id : getRpcId()
    
    Returns:
    
    String a rpc id
  - nextLocalRpcId
```
public static String nextLocalRpcId()
```
    get next thread rpc id rpc id rule : getRpcId()
    
    Returns:
    
    String a rpc id
  - getClientAppId
```
public static String getClientAppId()
```
    get the appId from local thread context if local thread context is null (sometimes it means you don't have any Transaction in your context), it is going to return "unknown"
    
    Returns:
    
    String appId
  - exportContext
```
public static TraceContext exportContext()
```
  - importContext
```
public static void importContext(TraceContext context)
```
  - isImportContext
```
public static boolean isImportContext()
```
  - redis
```
@Deprecated
public static void redis(String url,
                                     String command,
                                     long duration,
                                     boolean succeed)
```
    Deprecated.
    
    record the redis cost
    
    Parameters:
    
    url - the redis url
    
    command - the redis command
    
    duration - the cost time of redis calls
    
    succeed - whether succeed to call the redis
  - redis
```
@Deprecated
public static void redis(String url,
                                     String command,
                                     long duration,
                                     boolean succeed,
                                     String redisType)
```
    Deprecated.
    
    record the redis cost
    
    Parameters:
    
    url - the redis url
    
    command - the redis command
    
    duration - the cost time of redis calls
    
    succeed - whether succeed to call the redis
    
    redisType - whether RDB or Corvus
  - redis
```
@Deprecated
public static void redis(String url,
                                     String command,
                                     long duration,
                                     boolean succeed,
                                     RedisResponse response)
```
    Deprecated.
    
    record the redis cost and response
    
    Parameters:
    
    url - the redis url
    
    command - the redis command
    
    duration - the cost time of redis calls
    
    succeed - whether succeed to call the redis
    
    response - me.ele.arch.etrace.common.modal.RedisResponse the redis response information(hit and response size)
  - redis
```
@Deprecated
public static void redis(String url,
                                     String command,
                                     long duration,
                                     boolean succeed,
                                     RedisResponse response,
                                     String redisType)
```
    Deprecated.
    
    record the redis cost and response
    
    Parameters:
    
    url - the redis url
    
    command - the redis command
    
    duration - the cost time of redis calls
    
    succeed - whether succeed to call the redis
    
    response - me.ele.arch.etrace.common.modal.RedisResponse the redis response information(hit and response size)
    
    redisType - whether RDB or Corvus
  - redis
```
@Deprecated
public static void redis(String url,
                                     String command,
                                     long duration,
                                     boolean succeed,
                                     RedisResponse[] responses)
```
    Deprecated.
    
    record the redis cost and response
    
    Parameters:
    
    url - the redis url
    
    command - the redis command
    
    duration - the cost time of redis calls
    
    succeed - whether succeed to call the redis
    
    responses - me.ele.arch.etrace.common.modal.RedisResponse[] the redis responses information(hit and response size)
  - redis
```
@Deprecated
public static void redis(String url,
                                     String command,
                                     long duration,
                                     boolean succeed,
                                     RedisResponse[] responses,
                                     String redisType)
```
    Deprecated.
    
    record the redis cost and response
    
    Parameters:
    
    url - the redis url
    
    command - the redis command
    
    duration - the cost time of redis calls
    
    succeed - whether succeed to call the redis
    
    responses - me.ele.arch.etrace.common.modal.RedisResponse[] the redis responses information(hit and response size)
    
    redisType - whether RDB or Corvus
  - logHeartbeat
```
public static void logHeartbeat(String type,
                                String name,
                                String status,
                                String data,
                                Map<String,String> tags)
```
  - newCounter
```
public static Counter newCounter(String name)
```
    Counter counter = Trace.newCounter("metric-name"); //create a new Counter counter.addTag("key-1", "value-1"); // add tag counter.once(); // set value=1, when call once, the Counter finishes, refer to: Counter.once()
    Another way： //when call value(10), the Counter ends, refer to : Counter.value(long) Trace.newCounter("metric-name").addTag("key-1", "value-1").value(10);
    
    Parameters:
    
    name - the metric name
    
    Returns:
    
    Counter
  - newGauge
```
public static Gauge newGauge(String name)
```
    Gauge gauge = Trace.newGauge("metric-name"); //create a new Gauge gauge.addTag("key-1", "value-1").addTag("key-2", "value-2"); //add tag gauge.value(200); //set value=200, when call value(200), the Gauge finishes, refer to : Gauge.value(double)
    Another way: // when call value(100) , the Gauge finishes, refer to : Gauge.value(double) Trace.newGauge("metric-name").addTag("key-1", "value-1").value(100);
    
    Parameters:
    
    name - the metric name
    
    Returns:
    
    Gauge
  - newTimer
```
public static Timer newTimer(String name)
```
    The timer doesn't support the quantile(upper_85,upper_90 etc.), but another metric type : Histogram do. timer.setUpperEnable(false), means you get the metric type : Timer. Otherwise, it's Histogram.(default)
    For example: Timer timer = Trace.newTimer("metric-name"); //create a new Timer, the start time and time point is (System.currentTimeMillis()) timer.addTag("key-1", "value-1"); //add tag timer.addTag("key-2", "value-2"); //add tag //timer.setUpperEnable(false); //set the quantile enable, default : true //do business logic timer.end(); //the timer finishes. the cost time = (end time - start time)ms, the count = 1, refer to : Timer.end()
    Another way: // when call value(40) , the Timer finishes, the cost time = 40ms, the count = 1, refer to : Timer.value(long) Timer time = Trace.newTimer("metric-name").addTag("key-1", "value-1").addTag("key-2", "value-2").value(40);
    
    Parameters:
    
    name - the metric name
    
    Returns:
    
    Timer
  - newPayload
```
public static Payload newPayload(String name)
```
    Payload payload = Trace.newPayload("metric-name"); //create a new Payload, the time point is (System.currentTimeMillis()) payload.addTag("key-1", "value-1").addTag("key-2", "value-2"); //add tag payload.value(1000); //set value = 1000, count = 1, and the Payload finishes, refer to : Payload.value(long)
    Another way: // when call value(2000), the Payload finishes. Trace.newPayload("metric-name").addTag("key-1", "value-1").value(2000);
    
    Parameters:
    
    name - the metric name
    
    Returns:
    
    Timer

Class Trace

Method Summary

Methods inherited from class java.lang.Object

Method Detail

shutdownTrace

getStats

getCallStackProducerQueueSize

getTCPMessageSenderQueueSize

newEvent

logEvent

logEvent

logEvent

logEvent

logError

logError

logError

logError

newTransaction

hasTransaction

clean

hasContext

continueTrace

getCurrentRequestId

getRpcId

getCurrentRpcId

getCurrentRpcIdAndCurrentCall

removeContext

getCurrentRpcIdWithAppId

nextRemoteRpcId

nextLocalRpcId

getClientAppId

exportContext

importContext

isImportContext

redis

redis

redis

redis

redis

redis

logHeartbeat

newCounter

newGauge

newTimer

newPayload