Track Function Calls in Android Apps

Function tracking is the ability to monitor code-level individual functions during runtime for potential errors. By using the Ax.start() and Ax.end() APIs within the function definition, SDK will be able to monitor and report runtime issues with detailed data points.

Regular function call

Java

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    String userName = getUserNameFromDb("123-sd-12");

}

public String getUserNameFromDb(String userId){
    String userName = User.findById(userId).getName();
    return userName;
}

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_user)
    val userName = getUserNameFromDb("123-sd-12")
}

fun getUserNameFromDb(userId: String): String?{
    return User.findById(userId).getName()
}

Using Ax.start() and Ax.end() APIs

Java

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    
    String userName = getUserNameFromDb("123-sd-12");
}

@AX
public String getUserNameFromDb(String userId){
    Ax.start(new Object(){}, userId);

    String userName = User.findById(userId).getName();

    return Ax.end(new Object(){}, userName);
}

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_user)
    val userName = getUserNameFromDb("123-sd-12")
}

@AX
fun getUserNameFromDb(userId: String): String?{
    Ax.start(object {}, userId)

    //function definition.
    return Ax.end(object {}, UserDao.getNameWithId(userId))
}

Once Ax.start() and Ax.end() APIs are added to a function definition, errors like NULL return value, wrong return value and function execution delays will be captured and reported to the dashboard.

Things to Note:

1. It is mandatory to call both Ax.start() and Ax.end() functions at the start and end of your function definition.
2. The first parameter of both the APIs should be new Object(){} / object {}.
3. Make sure that the function is annotated using @AX.
4. By default, SDK monitors for NULL return value, negative return value in case of Boolean and if the function takes more than 1000 milliseconds to execute.
5. Please find the @AX section to learn more.
6. Use Ax.reportException API to report exceptions thrown during function invocation, if required.
7. The function parameters that are passed to Ax.start() during its invocation will be tagged along with issues reported in the Appxiom dashboard.
8. In case there is no return value, just call Ax.end(new Object(){}) at the end of the function definition.

@AX fields

It is mandatory to annotate every code level function that is to be tracked by the SDK with @AX annotation. @AX annotation allows customization in the way issues are reported during a tracked function execution.

Function ID

In case of function overloading, this field is mandatory. ID field gives the ability for the SDK to track functions in case of function overloading. In the case of tracking such functions, use the id field to assign a unique name for the functions.

Usage of function ID when using Ax.start() and Ax.end() APIs

In case of function overloading, simply set a unique name to the id field. This will allow the SDK to track overloaded functions.

Function Overriding with Ax.start and Ax.end

Java

@Override
protected void onCreate(Bundle savedInstanceState) {

    // No change needed here
    getUserNameFromDb("123-sd-12");

    // No change needed here
    getUserNameFromDb("user@app.com", "RENKDS123S");
}

@AX
public String getUserNameFromDb(String userId){
    Ax.start(new Object(){}, userId);

    String userName = User.findById(userId).getName();

    return Ax.end(new Object(){}, userName);
}

//Set a unique name to the functions using "id" field
@AX(id = "getUserNameFromDBWithEmailAndToken") 
public String getUserNameFromDb(String email, String token){
    Ax.start(new Object(){}, email, token);

    String userName = User.findByToken(token).getName();

    return Ax.end(new Object(){}, userName);
}

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_user)

    // No change needed here
    val userName = getUserNameFromDb("123-sd-12")

    // No change needed here
    val userName = getUserNameFromDb("user@app.com", "RENKDS123S")
}

@AX
fun getUserNameFromDb(userId: String): String?{
    Ax.start(object {}, userId)
    
    return Ax.end(object {}, User.findById(userId).getName())
}

//Set a unique name to the functions using "id" field
@AX(id = "getUserNameFromDbWithEmailAndToken")
fun getUserNameFromDb(email: String, token: String): String?{
    Ax.start(object {}, email, token)
    
    return Ax.end(object {}, User.findUniqueByProperties(email,token).getName())
}

Expected Execution Time

Type: 5 | Default Severity: Major

By default, if a tracked function takes more than 1000 milliseconds to execute, an issue report will be sent to the dashboard.
Set a custom expected execution time using the field expectedExecutionTime in @AX annotation.

Once this field is set with a custom value, and the corresponding function execution takes more than the set amount of time, an issue report will be sent to the dashboard.

Expect Null

Type: 2 | Default Severity: Major

By default, if a tracked function returns NULL during its execution, an issue report will be sent to the dashboard.
Set the field expectNull to 'true' to prevent SDK from reporting NULL issues.

Setting expectNull using @AX annotation

Java

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    
    ...
}

@AX(expectNull = true)
public String getUserNameFromDb(String userId){
    ...
}

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_user)
    ...
}

@AX(expectNull = true)
fun getUserNameFromDb(userId: String): String?{
    ...
}

Expected Boolean Value

Type: 4 | Default Severity: Major

By default, if a tracked function with return type Boolean returns 'false' during its execution, an issue report will be sent to the dashboard.
Instead if an issue report needs to be raised if return value is 'true', set the field expectedBooleanValue to 'false'.

Setting expectedBooleanValue using @AX annotation

Java

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    
    ...
}

@AX(expectedBooleanValue = false)
public Boolean verifyUser(String userId){
    ...
}

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_user)
    ...
}

@AX(expectedBooleanValue = false)
fun verifyUser(userId: String): Boolean?{
    ...
}

Set Range Check of Return value

Type: 3 | Default Severity: Major

If the tracked function returns a Number type (e.g. Integer, Double, Float). Use min, max, minDecimal, maxDecimal fields to set expected upper and lower limits of return value.
Once set, if the function returns a value outside the min and max values, corresponding issue report will be raised to the Appxiom dashboard.

Setting range check of return value using @AX annotation

Java

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    
    ...
}

@AX(min = 200)
public Integer walletBalanceOfUser(String userId){
    ...
}

@AX(min = 10, max = 3000)
public Integer amountTypedByUserForWalletRefill(String userId){
    ...
}

@AX(minDecimal = 10)
public Double getTaxComponentForProduct(String productId){
    ...
}

@AX(minDecimal = 10, maxDecimal = 20)
public Double calculateFinalTaxPercentageCollected(String userId){
    ...
}

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    ...
}

@AX(min = 200)
fun walletBalanceOfUser(userId: String): Integer?{
    ...
}
@AX(min = 10, max = 3000)
fun amountTypedByUserForWalletRefill(userId: String): Integer?{
    ...
}

@AX(minDecimal = 10)
fun getTaxComponentForProduct(productId: String): Double?{
    ...
}
@AX(minDecimal = 10, maxDecimal = 20)
fun calculateFinalTaxPercentageCollected(userId: String): Double?{
    ...
}

---

Frequently Asked Questions (FAQs)

Q: What is function tracking in Appxiom SDK?
A: Function tracking allows you to monitor individual function executions for errors, null/incorrect return values, and performance issues in real time.

Q: How do I enable function tracking?
A: Annotate your function with @AX and use Ax.start() and Ax.end() at the start and end of your function definition.

Q: What types of issues are automatically detected?
A: The SDK detects null return values, negative/incorrect return values, execution delays during function execution.

Q: Is it mandatory to use both Ax.start() and Ax.end()?
A: Yes, both must be called at the start and end of the function for tracking.

Q: Can I track overloaded or overridden functions?
A: Yes, use the id field in @AX to assign a unique identifier for each overloaded function.

Q: What happens if my function does not return a value?
A: Call Ax.end(new Object(){}) at the end of the function to complete tracking.

Q: Can I customize which issues are reported?
A: Yes, you can use fields like expectNull, expectedBooleanValue, min, max, minDecimal, maxDecimal in the @AX annotation.

Q: How do I report exceptions thrown during function execution?
A: Use the Ax.reportException API to report exceptions inside try-catch blocks.

Q: Is function tracking available for both Java and Kotlin?
A: Yes, the SDK supports function tracking in both Java and Kotlin.

---