SDK API

Due to the diversity of C/C++ application frameworks/architectures, Tingyun 3.0 CSDK provides two sets of SDK methods, for asynchronous and synchronous invocation frameworks respectively.

Header file inclusion:

#include <tingyun.h>

Initialize SDK:

	void TingYunAgentInit();
	Agent initialization function.
	This function is not required to be called explicitly.
	If this function is not called in the application code, it will be called implicitly when the first transaction instrumentation is triggered.
	Since the agent initialization process is performed asynchronously in the background, transaction data before the agent is fully initialized will not be collected.

Asynchronous API Methods

Create Transaction

Description: In application performance analysis, we use Action to define a complete transaction, which usually corresponds to a complete HTTP request process.

Code:

	// Parameters:
	//	uri :           The transaction name corresponding to the Action. If empty, the class name::function name where the function is located is used.
	//	Return value :    Transaction Id.
	TActionId CreateAction(const char *uri);
	// Function:        Define a transaction process.
	// Invocation timing: When the client request processing starts.

Create Background Task

Description: In server applications, there may be transaction processes outside of service responses, such as scheduled tasks. We define these as background tasks.

Code:

	// Parameters:
	//	cmd :        The transaction name corresponding to the background task. If empty, the class name::function name where the function is located is used.
	//	Return value :    Transaction Id.
	TActionId CreateBackGroundAction(const char *cmd);
	// Function:        Define a background transaction process.
	// Invocation timing: When the background task starts.

End Transaction

Description: Method called when the transaction ends, to measure and analyze the execution process of the transaction.

Code:

	// Parameters:
	//	action :     Transaction id.
	void ActionDestroy(TActionId action);
	// Function:        End the transaction process.
	// Invocation timing: When the transaction processing ends.
	// Note:        After ActionDestroy is called, it means the transaction data collection is complete, and the action and all components created by the action become invalid.

Create Component

Component Description

A transaction usually contains multiple component processes, and component processes may further be divided into several other component processes. We define such sub-processes as Components. By analyzing the time consumption of the component tree, we can locate performance bottlenecks in the transaction execution process.

Create Component from Action

General Component

	// Method 1:
	// If the function name is not specified, the current function name is used as the component name.
	// Parameters 
	//	action:          Transaction Id.
	//	Return value:         Component Id.
	TComponentId ACreateComponent(TActionId action);
	// Function:             Start data collection for a component. This API uses the current function name as the component name.
	// Invocation timing:      When a potentially time-consuming sub-process starts.
	
	// Method 2:
	// Custom component name.
	// Parameters:
	//	action:                    Transaction Id.
	//	ComponentName: Custom component name.
	//	Return value:                   Component Id.
	TComponentId ActionCreateComponent(TActionId action, const char *ComponentName);
	// Function:                      Same as above, this API uses a custom name as the component name.
	// Invocation timing:               Same as above.

Database Component

	// Method 1:      When there is an SQL statement, use the SQL statement for automatic analysis.
	// Parameters:
	//	action:    Transaction Id.
	//	type:       Database type: "Mysql"/"Postgresql".
	//	host:       Database host address.
	//	dbname: Database name.
	//	sql:         Executed SQL statement.
	//	Return value:   Component Id.
	TComponentId CreateSQLComponent(TActionId action, const char *type, const char *host, const char *dbname, const char *sql);
	// Function:         Start data collection for a database call process, requires passing the SQL statement. The internal logic will parse the database operation type and table name as part of the component name.
	// Invocation timing:  When the database process starts.
	
	// Method 2: When there is no SQL statement, pass the table name and operation name (select/update/insert/delete).
	// Parameters:
	//	action:      Transaction Id.
	//	type:         Database type: "Mysql"/"Postgresql".
	//	host:         Database host address.
	//	dbname:   Database name.
	//	table:        Table name.
	//	op:            Operation name on the table.
	//	Return value:     Component Id.
	TComponentId CreateDBComponent(TActionId action, const char *type, const char *host, const char *dbname, const char *table, const char *op);
	// Function:           Same as above, the difference is that the table name and operation method (select/update/insert/delete) are specified explicitly.
	// Invocation timing:    Same as above.

NoSQL Component

	// Parameters:
	//	action:            Transaction Id.
	//	type:               Database type: "Mysql"/"Postgresql".
	//	host:               Database host address.
	//	dbname:         Database name.
	//	object_name: Object name.
	//	op:                  Operation name on the object.
	//	Return value:           Component Id.
	TComponentId CreateNoSQLComponent(TActionId action, const char *type, const char *host, const char *dbname, const char *object_name, const char *op);
	// Function:                  Start data collection for a NoSQL database call process.
	// Invocation timing:           When the NoSQL process starts.

External Call Component (RPC, HTTP, etc.)

	// Custom component name.
	// Parameters:
	//	action:     Transaction Id.
	//	url:           External call url.
	//	Return value:    Component Id.
	TComponentId CreateExternalComponent(TActionId action, const char *url);
	// Function:          Start data collection for an external call, which can be an HTTP request to another server or an RPC call.
	// Invocation timing:   When the external call starts.

MQ Call Component (Producer, Consumer)

	// Custom component name.
	// Parameters:
	//	action:   Transaction Id.
	//	type:      MQ type: RabbitMQ, ActiveMQ, Kafka... 
	//	host:      MQ address.
	//	queue:   Queue name.
	//	Return value:  Component Id.
	TComponentId CreateConsumerComponent(TActionId action, const char *type, const char *host, const char *queue);
	// Function:        Start data collection for a message queue consumer.
	// Invocation timing: When the MQ consumer starts.

	// Custom component name.
	// Parameters:
	//	action:     Transaction Id.
	//	type:        MQ type: RabbitMQ, ActiveMQ, Kafka... 
	//	host:        MQ address.
	//	queue:     Queue name.
	//	Return value:    Component Id.
	TComponentId CreateProducerComponent(TActionId action, const char *type, const char *host, const char *queue);
	// Function:          Start data collection for a message queue producer.
	// Invocation timing:   When the MQ producer starts.

Create Component from Component

	// Method 1:
	// If the function name is not specified, the current function name is used as the component name.
	// Parameters 
	//	parent:      Parent component Id.
	//	Return value:      Component Id.
	TComponentId CCreateComponent(TComponentId parent);
	// Function:           Start data collection for a component. When a time-consuming process is divided into several sub-processes, we need to collect the time consumption of each sub-process for detailed performance analysis. This API can build a call tree, and by analyzing the time consumption of each process, solve performance problems.
	
	// Method 2:
	// Custom component name
	// Parameters:
	//	parent:                   Parent component Id.
	//	ComponentName: Custom component name.
	//	Return value:                   Component Id.
	TComponentId ComponentCreateComponent(TComponentId parent, const char *ComponentName);
	// Function:                        Same as above, the difference is that this API uses a custom process name.
	// Invocation timing:                 Same as above.

Component Error Collection

	// Parameters:
	//	component:    Component id.
	//	message:       Error message.
	void ComponentSetError(TComponentId component, const char *message);
	// Function:                 When an error occurs in the component process, use this API to record the code line and call stack to assist in error analysis.
	// Invocation timing:          When an error occurs in the corresponding component process.

End Component

	// Parameters:
	//	component:    Component id.
	void ComponentFinish(TComponentId component);
	// Function:                End data collection for a component.
	// Invocation timing:         When the execution of the corresponding component process is completed, such as when a database process or an external call is completed.

When a sub-process ends, you need to call the corresponding Component.Finish() to complete data collection.

Cross-application Tracing

• Application Topology When there are mutual calls between multiple applications under one account, you can use the API to trace the call relationships between applications. The caller uses CreateTrackId, the callee uses SetTrackId, and the topology will show the "caller" -> "callee" relationship.

Client:

	// Flow:
	//1. Create an external call component.
	//2. Call ComponentCreateTrackId to generate a cross-application trace id (string).
	//3. Send the id to the server.