Skip to main content

Interface Description

Set the user ID​

By setting the "user ID", the performance data of a specific user is retrieved on the Tingyun platform through the ID.

  • Interface
// username: Username, string type. Length limit: 256 characters.
tingyun.setUid(username)
  • Examples
import tingyun from '@/agent/init'

// ... 
tingyun.setUid('<userid>')

Vue Route Monitoring​

  • Interface
// router VueRouter Instance Object
tingyun.wrapVueRouter(router);
  • Example:
// Introducing the Probe
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 }
  ]
})

// Call the wrapVueRouter interface with the router object.
tingyun.wrapVueRouter(router)

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

JS error reporting​

This interface can be used to upload the triggered JS errors to the Tingyun platform, so that developers can collect and troubleshoot JS errors.

By default, the probe will monitor the Vue.config.errorHandler trigger and report the JS error. If the item itself is also registered Vue.config.errorHandler, when the errorHandler is synchronously registered in the entry file, the probe can generally automatically monitor "Confirm that the Vue. Config. ErrorHandler monitoring is valid during automatic monitoring". However, when the errorHandler is registered late, the automatic monitoring of the probe will fail. In this case, you need to use the probe API captureException to manually report in the custom error handler.

  • Interface
tingyun.captureException(err[, options])

Parameters:

  • Err: error object

    • Message: Error message is optional
    • Stack: error stack optional
    • FileName: string Specify the file name of the error. It is optional. It will be automatically parsed from the stack without transmission
    • LineNumber: number Specify the error line number. Optional. Automatically parse from the stack without transmission.
    • ColumnNumber: number Specify the error column number. Optional. Automatically parse from the stack without transmission

  • Options: Extra options. Object type. Optional

    • Contexts: Extra additional data. Object type. Optional
    • Breadcrumbs: breadcrumb data. Array. Optional Data Item Type Description
      • Timestamp: number millisecond timestamp, must
      • Type: string type, must
      • Category: string category, must
      • Level: string level, must
      • Message: string message, optional
      • Data: object additional data, optional
    • Category: Error type. Optional. Value: JS (JS error, default) or other (other error)

  • Examples

  • User-defined Error Handler reports JS error

  1. Report JS errors in the custom Error Handler
Vue.config.errorHandler = function (err) {
  // Report Errors
  tingyun.captureException(err)
}
  1. Turn off the automatic JS error monitoring switch to prevent repeated monitoring

agent/init.js:

tingyun.init({
  // ...
  jsError: {
    // Disable Automatic Monitoring of JavaScript Errors
    enabled: false
  }
})
  • Manually report errors

After some JS errors are triggered, they will not be triggered Vue.config.errorHandler. At this time, JS errors can be reported manually.

import tingyun from '@/agent/init'

// ...

try {
  // ... 
} catch(e) {
  tingyun.captureException(e)
}

Custom action​

Define a Business Operation by calling the Custom Operation interface to analyze its performance

  • Interface
const action = tingyun.newAction(optionsStart);

action.end(optionsEnd);

Parameters:

  • OptionsStart Actions CI Object

    • Key: name of the operation. String type. Must
    • Context: Additional data contained by the operation. Object type. Optional
    • Duration: Set the operation time. For an operation that is sent immediately, you can set this configuration to specify the operation time. The number type. Optional
    • Timeout: operation timeout time, 10 minutes by default, operation after timeout is discarded, number type, optional
    • Status: Set the operation status to success or fail. The default is success. The operation is valid only in the immediate sending mode. String type. Optional
    • Immediate: Whether to send this operation immediately, Boolean type, default is false. Optional

  • OptionsEnd Ends the action configuration object. Optional

    • Context: Additional data contained by the operation. Object type. Optional
    • Status: Set the operation status to success or fail. The default is success. String type. Optional

  • Examples The following example demonstrates 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 submission successful, end operation.
          action.end()
        }else {
          // Order submission failed, end operation, mark operation as failed, and upload the failed order number.
          action.end({
            status: 'fail',
            context: {
              orderId: orderId
            }
          })
        }
      })
    }
  }
}

Custom action usage:

  • Use the newAction create operation to get the operation object, and the operation starts simultaneously when calling the API.
  • Use the action object end method to end and report the action. The action will contain requests initiated during the duration of the action
  • Set context properties in end method parameters to report custom data, and set status properties to set the success or failure status of the operation

Configure the acquisition parameters​

The probe supports the configuration of the URL parameter, request header, request body, return header and return body of the request sent by the fetch interface of the collection stream module.

Configuration format:

tingyun.init({
  // ...
  common: {
    paramCollection: [
      {
        // number
        type: <Location Type Collection>
        key: '<Field Name Collection>'
      },
      ...
    ]
  }
})

Value of type:

  • 1: URL
  • 2: Request header
  • 3: Request body, which supports request body in JSON string format and request body in application/x-www-form-urlencoded format, and supports configuration of JSON Path
  • 4: Go back
  • 5: Return body, support JSON format return body, support configuration of JSON Path

Configuration example:

tingyun.init({
  // ...
  common: {
    paramCollection: [
      // Retrieve the token parameter from the URL parameters.
      {
        type: 1,
        key: 'token'
      },
      // Retrieve the Content-Type header from the request headers.
      {
        type: 2,
        key: 'content-type'
      },
      // Retrieve the delay field from the request body.
      {
        type: 3,
        key: 'delay'
      },
      // Retrieve the Server-Timing response header from the response headers.
      {
        type: 4,
        key: 'Server-Timing'
      },
      // Configure JSON Path to retrieve information from the response body.
      // If the response body is：{"code":200,"message":"success","data":[{"id":1,"name":"xxx","lon":116.43,"lat":39.92}]} 
      // The configuration to retrieve the "name" field from the first item of the "data" array in the response body would be:
      {
        type: 5,
        key: 'data[0].name'
      }
    ]
  }
})

Configuration item​

JS SDK supports the switch of user-defined configuration function item, and the corresponding function item can be configured as required.

// The probe supports all configuration options.
export type ConfigOptions = {
    // If the protocol is not specified, the default protocol for data upload is HTTPS.
    domain: string
    // App token
    token: string
    // App key, The configuration for Tingyun cross-application tracing is mandatory.
    key?: string
    // App version
    release?: string
    // vue router Object
    router?: VueRouterInstance
    // Public Configuration
    common?: {
        // Monitor route loading, default is true.
        routerEnabled?: boolean;
        // Parameter Collection Configuration
        paramCollection?: ParamCollectConfig[];
      	// Use the original domain value as the upload address. Default is false. If the probe detects that the domain does not start with "http:" or "https:", it will forcibly concatenate the "https" protocol.
        // If you want to send using a completely custom address, set this option to true.
        useRawDomain?: boolean;
    }
    // JS Error Monitoring Configuration
    jsError?: {
        // Automatic monitoring of JavaScript errors switch, default is true.
        enabled?: boolean
      	// Receive events sent after native monitoring of JavaScript errors, default is true.
        nativeErrorEnabled?: boolean
        // Report JavaScript errors with empty filenames, default is true.
        uploadEmptyFileErrors?: boolean
      	// The event name registered when using the globalEvent module, default is "tingyunWeexError".
        nativeErrorEventName?: string
    }
    // Ajax Monitoring Configuration
    ajax?: {
        // Ajax monitoring master switch, default is true.
        enabled?: boolean
    }
    // Cross-Application Tracing Configuration
    requestTracing?: {
      // Trace propagator configuration, default is "tingyun", optional values: "tingyun", "sw8", "w3c-trace-context".
      propagators?: string[]
      // Specify URLs to include in the propagator header, including relationships.
      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
type ParamCollectConfig = {
    type: ParamCollectType
    key: string
}