This is an automated email from the ASF dual-hosted git repository. wusheng pushed a commit to branch polish-browser-doc in repository https://gitbox.apache.org/repos/asf/skywalking.git
commit 640a99fd7e90bf084995b63fdc6b204934e0140d Author: wu-sheng <[email protected]> AuthorDate: Thu Feb 13 13:47:22 2025 +0800 Polish the browser doc for client-js 1.0 --- docs/en/api/browser-http-api-protocol.md | 174 ------------------------------ docs/en/api/browser-protocol.md | 176 +++++++++++++++++++++++++++++-- docs/menu.yml | 4 +- 3 files changed, 170 insertions(+), 184 deletions(-) diff --git a/docs/en/api/browser-http-api-protocol.md b/docs/en/api/browser-http-api-protocol.md deleted file mode 100644 index 7f1e350363..0000000000 --- a/docs/en/api/browser-http-api-protocol.md +++ /dev/null @@ -1,174 +0,0 @@ -# HTTP API Protocol - -HTTP API Protocol defines the API data format, including API request and response data format. -They use the HTTP1.1 wrapper of the official [SkyWalking Browser Protocol](browser-protocol.md). Read it for more details. - -## Performance Data Report - -Detailed information about data format can be found in [BrowserPerf.proto](https://github.com/apache/skywalking-data-collect-protocol/blob/master/browser/BrowserPerf.proto). - -### POST http://localhost:12800/browser/perfData - -Send a performance data object in JSON format. - -Input: - -```json -{ - "service": "web", - "serviceVersion": "v0.0.1", - "pagePath": "/index.html", - "redirectTime": 10, - "dnsTime": 10, - "ttfbTime": 10, - "tcpTime": 10, - "transTime": 10, - "domAnalysisTime": 10, - "fptTime": 10, - "domReadyTime": 10, - "loadPageTime": 10, - "resTime": 10, - "sslTime": 10, - "ttlTime": 10, - "firstPackTime": 10, -} -``` - -OutPut: - -HTTP Status: 204 - -### POST http://localhost:12800/browser/perfData/webVitals - -Send a performance data object in JSON format. Since client-js 1.0.0, the following attached metrics are reported. - -Input: - -```json -{ - "service": "web", - "serviceVersion": "v0.0.1", - "pagePath": "/index.html", - "fmpTime": 10, - "clsTime": 10, - "lcpTime": 10, -} -``` - -OutPut: - -HTTP Status: 204 - -### POST http://localhost:12800/browser/perfData/webInteractions - -Send a performance data object in JSON format. Since client-js 1.0.0, the following attached metrics are reported. - -Input: - -```json -[ - { - "service": "web", - "serviceVersion": "v0.0.1", - "pagePath": "/index.html", - "inpTime": 10, - } -] -``` - -OutPut: - -HTTP Status: 204 - -### POST http://localhost:12800/browser/perfData/resources - -Send a static resources data object in JSON format. Since client-js 1.0.0, the following attached metrics are reported. - -Input: - -```json -[ - { - "service": "web", - "serviceVersion": "v0.0.1", - "pagePath": "/index.html", - "name": "vue.js", - "duration": 600, - "size": 100000, - "protocol": "h2", - "type": "script", - } -] -``` - -OutPut: - -HTTP Status: 204 - -## Error Log Report - -Detailed information about data format can be found in [BrowserPerf.proto](https://github.com/apache/skywalking-data-collect-protocol/blob/master/browser/BrowserPerf.proto). - -### POST http://localhost:12800/browser/errorLogs - -Send an error log object list in JSON format. - -Input: - -```json -[ - { - "uniqueId": "55ec6178-3fb7-43ef-899c-a26944407b01", - "service": "web", - "serviceVersion": "v0.0.1", - "pagePath": "/index.html", - "category": "ajax", - "message": "error", - "line": 1, - "col": 1, - "stack": "error", - "errorUrl": "/index.html" - }, - { - "uniqueId": "55ec6178-3fb7-43ef-899c-a26944407b02", - "service": "web", - "serviceVersion": "v0.0.1", - "pagePath": "/index.html", - "category": "ajax", - "message": "error", - "line": 1, - "col": 1, - "stack": "error", - "errorUrl": "/index.html" - } -] -``` - -OutPut: - -HTTP Status: 204 - -### POST http://localhost:12800/browser/errorLog - -Send a single error log object in JSON format. - -Input: - -```json -{ - "uniqueId": "55ec6178-3fb7-43ef-899c-a26944407b01", - "service": "web", - "serviceVersion": "v0.0.1", - "pagePath": "/index.html", - "category": "ajax", - "message": "error", - "line": 1, - "col": 1, - "stack": "error", - "errorUrl": "/index.html" -} -``` - -OutPut: - -HTTP Status: 204 diff --git a/docs/en/api/browser-protocol.md b/docs/en/api/browser-protocol.md index 1a57f11bac..3fb3d71e7f 100644 --- a/docs/en/api/browser-protocol.md +++ b/docs/en/api/browser-protocol.md @@ -4,16 +4,176 @@ Browser protocol describes the data format between [skywalking-client-js](https: ## Overview -Browser protocol is defined and provided in [gRPC format](https://github.com/apache/skywalking-data-collect-protocol/blob/master/browser/BrowserPerf.proto), -and also implemented in [HTTP 1.1](browser-http-api-protocol.md) +Browser protocol is defined in [gRPC format](https://github.com/apache/skywalking-data-collect-protocol/blob/master/browser/BrowserPerf.proto) and +exposed in HTTP 1.1 for the browser. -### Send performance data and error logs +### Performance Data Report -You can send performance data and error logs using the following services: +Detailed information about data format can be found in [BrowserPerf.proto](https://github.com/apache/skywalking-data-collect-protocol/blob/master/browser/BrowserPerf.proto). -1. `BrowserPerfService#collectPerfData` for performance data format. -1. `BrowserPerfService#collectErrorLogs` for error log format. +#### POST http://localhost:12800/browser/perfData -For error log format, note that: +Send a performance data object in JSON format. -1. `BrowserErrorLog#uniqueId` should be unique in all distributed environments. +Input: + +```json +{ + "service": "web", + "serviceVersion": "v0.0.1", + "pagePath": "/index.html", + "redirectTime": 10, + "dnsTime": 10, + "ttfbTime": 10, + "tcpTime": 10, + "transTime": 10, + "domAnalysisTime": 10, + "fptTime": 10, + "domReadyTime": 10, + "loadPageTime": 10, + "resTime": 10, + "sslTime": 10, + "ttlTime": 10, + "firstPackTime": 10, +} +``` + +OutPut: + +HTTP Status: 204 + +#### POST http://localhost:12800/browser/perfData/webVitals + +Send a performance data object in JSON format. Since client-js 1.0.0, the following attached metrics are reported. + +Input: + +```json5 +{ + "service": "web", + "serviceVersion": "v0.0.1", + "pagePath": "/index.html", + "fmpTime": 10, // Deprecated since skywalking-client-js 1.0. This is no longer recommended. Please use the `useWebVitals` instead. + /* NOTE, Safari does not support all core web vitals, and Firefox does not support `CLS`. */ + "clsTime": 10, + "lcpTime": 10, +} +``` + +OutPut: + +HTTP Status: 204 + +#### POST http://localhost:12800/browser/perfData/webInteractions + +Send a performance data object in JSON format. Since client-js 1.0.0, the following attached metrics are reported. + +Input: + +```json +[ + { + "service": "web", + "serviceVersion": "v0.0.1", + "pagePath": "/index.html", + "inpTime": 10, + } +] +``` + +OutPut: + +HTTP Status: 204 + +#### POST http://localhost:12800/browser/perfData/resources + +Send a static resources data object in JSON format. Since client-js 1.0.0, the following attached metrics are reported. + +Input: + +```json +[ + { + "service": "web", + "serviceVersion": "v0.0.1", + "pagePath": "/index.html", + "name": "vue.js", + "duration": 600, + "size": 100000, + "protocol": "h2", + "type": "script", + } +] +``` + +OutPut: + +HTTP Status: 204 + +### Error Logs Report + +#### POST http://localhost:12800/browser/errorLogs + +Send an error log object list in JSON format. + +Input: + +```json +[ + { + "uniqueId": "55ec6178-3fb7-43ef-899c-a26944407b01", + "service": "web", + "serviceVersion": "v0.0.1", + "pagePath": "/index.html", + "category": "ajax", + "message": "error", + "line": 1, + "col": 1, + "stack": "error", + "errorUrl": "/index.html" + }, + { + "uniqueId": "55ec6178-3fb7-43ef-899c-a26944407b02", + "service": "web", + "serviceVersion": "v0.0.1", + "pagePath": "/index.html", + "category": "ajax", + "message": "error", + "line": 1, + "col": 1, + "stack": "error", + "errorUrl": "/index.html" + } +] +``` + +OutPut: + +HTTP Status: 204 + +### POST http://localhost:12800/browser/errorLog + +Send a single error log object in JSON format. + +Input: + +```json +{ + "uniqueId": "55ec6178-3fb7-43ef-899c-a26944407b01", + "service": "web", + "serviceVersion": "v0.0.1", + "pagePath": "/index.html", + "category": "ajax", + "message": "error", + "line": 1, + "col": 1, + "stack": "error", + "errorUrl": "/index.html" +} +``` + +OutPut: + +HTTP Status: 204 + +Note, `BrowserErrorLog#uniqueId` should be unique in the whole distributed environments. diff --git a/docs/menu.yml b/docs/menu.yml index 6643b4013b..a48b34322e 100644 --- a/docs/menu.yml +++ b/docs/menu.yml @@ -306,9 +306,9 @@ catalog: catalog: - name: "Meter APIs" path: "/en/api/meter" - - name: "Browser performance APIs" + - name: "Browser Performance APIs" path: "/en/api/browser-protocol" - - name: "JVM metrics APIs" + - name: "JVM Metrics APIs" path: "/en/api/jvm-protocol" - name: "Logging" path: "/en/api/log-data-protocol"
