API Reference

Setting User ID

By setting the "user identifier" in the Tingyun platform, you can use this identifier to query specific user performance data.

• API

tingyun.setUid(username)

Example

import tingyun from '@/agent/init'
// ...
tingyun.setUid('<user id>')

Monitoring Vue Router

• API

tingyun.wrapVueRouter(router);

Example:

import tingyun from '@/agent/init'
import App from '@/App.vue'
import Home from '@/routes/Home.vue'
import About from '@/routes/About.vue'
import VueRouter from 'vue-router';

Vue.use(VueRouter)

const router = new VueRouter({
  mode: 'abstract',
  routes: [
    { path: '/', redirect: '/home' },
    { path: '/home', component: Home },
    { path: '/about', component: About }
  ]
})

tingyun.wrapVueRouter(router)

new Vue({
  el: '#root', 
  router: router,
  render: h => h(App),
})

Reporting JavaScript Errors

Use this API to upload triggered JS errors to the Tingyun platform for developers to collect and troubleshoot JS errors.

The agent will monitor and report JS errors triggered by Vue.config.errorHandler by default. If your project also registers Vue.config.errorHandler, and both are registered synchronously in the entry file, the agent can automatically monitor (ensure Vue.config.errorHandler monitoring is effective). If the errorHandler is registered later, the agent's automatic monitoring will fail. In this case, use the agent API captureException to manually report JS errors in your custom errorHandler.

• API

tingyun.captureException(err[, options])

Parameters:

• err: Error object
  • message: Error message (optional)
  • stack: Error stack (optional)
  • fileName: string, error file name (optional, if not provided, will be parsed from stack)
  • lineNumber: number, error line number (optional, if not provided, will be parsed from stack)
  • columnNumber: number, error column number (optional, if not provided, will be parsed from stack)
• options: Additional options. Object type. Optional
  • contexts: Additional data. Object type. Optional
  • breadcrumbs: Breadcrumbs data. Array. Optional Data item types:
    • timestamp: number, timestamp in milliseconds, required
    • type: string, required
    • category: string, required
    • level: string, required
    • message: string, optional
    • data: object, optional
  • category: Error type. Optional. Values: js (default) or other

Example

• Manually reporting JS errors in a custom errorHandler

Vue.config.errorHandler = function (err) {
  tingyun.captureException(err)
}

• Disabling automatic JS error monitoring to prevent duplicate monitoring

agent/init.js:

tingyun.init({
  // ...
  jsError: {
    enabled: false
  }
})

• Manually reporting errors

Some JS errors may not trigger Vue.config.errorHandler. In this case, you can manually report JS errors.

import tingyun from '@/agent/init'
// ...
try {
  // ... 
} catch(e) {
  tingyun.captureException(e)
}

Customizing Operation

Use the "custom operation" API to define a "business operation" for performance analysis.

• API

const action = tingyun.newAction(optionsStart);
action.end(optionsEnd);

Parameters:

• optionsStart: Operation configuration object
  • key: Operation name. String type. Required
  • context: Additional data included in the operation. Object type. Optional
  • duration: Set operation time. For immediate operations, you can use this to specify the operation time. Number type. Optional
  • timeout: Operation timeout. Default is 10 minutes. Operations are discarded after timeout. Number type. Optional
  • status: Set operation status as success or fail. Default is success. Only effective in immediate mode. String type. Optional
  • immediate: Whether to send this operation immediately. Boolean type. Default is false. Optional
• optionsEnd: End operation configuration object. Optional
  • context: Additional data included in the operation. Object type. Optional
  • status: Set operation status as success or fail. Default is success. String type. Optional

Example

Below is an example demonstrating a submit order operation:

import tingyun from '@/agent/init'
//... 
export default {
  methods: {
    submitOrder(orderId) {
      // Create an operation named submitOrder
      const action = tingyun.newAction({
        key: 'submitOrder'
      })
      fetch({
        url: '...',
        method: 'POST',
        body: '...'
      }, function (response) {
        if (response.ok) {
          // Order submitted successfully, end operation
          action.end()
        } else {
          // Order submission failed, end operation, mark as failed, and upload the failed order ID
          action.end({
            status: 'fail',
            context: {
              orderId: orderId
            }
          })
        }
      })
    }
  }
}

Custom operation usage:

• Use newAction to create an operation and get the operation object. The operation starts when the API is called.
• Use the operation object's end method to end and report the operation. The operation will include requests initiated during the operation duration.
• Set the context property in the end method parameter to report custom data, and set the status property to indicate the operation's success or failure.

Configuring Parameter Collection

The agent supports configuring the collection of URL parameters, request headers, request body, response headers, and response body for requests sent by the stream module fetch interface.

Configuration format:

tingyun.init({
  // ...
  common: {
    paramCollection: [
      {
        type: <collection type>
        key: '<field name>'
      },
      ...
    ]
  }
})

type values:

• 1: URL
• 2: Request header
• 3: Request body (supports JSON string and application/x-www-form-urlencoded formats, supports JSON Path configuration)
• 4: Response header
• 5: Response body (supports JSON format, supports JSON Path configuration)

Example configuration:

tingyun.init({
  // ...
  common: {
    paramCollection: [
      // Get token parameter from URL
      {
        type: 1,
        key: 'token'
      },
      // Get content-type from request header
      {
        type: 2,
        key: 'content-type'
      },
      // Get delay field from request body
      {
        type: 3,
        key: 'delay'
      },
      // Get Server-Timing from response header
      {
        type: 4,
        key: 'Server-Timing'
      },
      // Use JSON Path to get information from response body
      // If the response body is: {"code":200,"message":"Success","data":[{"id":1,"name":"xxx","lon":116.43,"lat":39.92}]}
      // The following configuration gets the name field from the first item in the data array
      {
        type: 5,
        key: 'data[0].name'
      }
    ]
  }
})

Configuration Options

The JS SDK supports custom configuration options, which can be set as needed.

// All configuration options supported by the agent
export type ConfigOptions = {
    // Data upload address. If protocol is not specified, https is used by default
    domain: string
    // Application token
    token: string
    // Application key, required for cross-application tracing with Tingyun
    key?: string
    // Application version
    release?: string
    // vue router object
    router?: VueRouterInstance
    // Common configuration
    common?: {
        // Monitor router loading, default true
        routerEnabled?: boolean;
        // Parameter collection configuration
        paramCollection?: ParamCollectConfig[];
        // Use the original value of domain as the upload address. Default false. If domain does not start with http: or https:, https protocol will be used by default. Set to true to use a fully custom address.
        useRawDomain?: boolean;
    }
    // JS error monitoring configuration
    jsError?: {
        // Enable automatic JS error monitoring. Default true
        enabled?: boolean
        // Receive events sent by native monitoring JS errors. Default true
        nativeErrorEnabled?: boolean
        // Report JS errors with empty file names. Default true
        uploadEmptyFileErrors?: boolean
        // Event name registered when using the globalEvent module. Default tingyunWeexError
        nativeErrorEventName?: string
    }
    // Ajax monitoring configuration
    ajax?: {
        // Ajax monitoring switch. Default true
        enabled?: boolean
    }
    // Cross-application tracing configuration
    requestTracing?: {
      // Trace propagator configuration. Default tingyun. Optional: tingyun, sw8, w3c-trace-context
      propagators?: string[]
      // Specify URLs to add propagator headers to (substring match)
      propagationTargets?: string[]
    }
}

type VueRouterInstance = {
    afterEach: any
    [key: string]: any
};

const ParamCollectTypes = {
    URL: 1,
    REQ_HEADER: 2,
    REQ_BODY: 3,
    RES_HEADER: 4,
    RES_BODY: 5,
} as const

type ParamCollectType = typeof ParamCollectTypes[keyof typeof ParamCollectTypes];

// Parameter collection configuration item
type ParamCollectConfig = {
    type: ParamCollectType
    key: string
}