Observer¶

The observer is a component used to observe the internal status of the service, including service status changes, connection and traffic statistics, and the observer reports this information through events.

Limitation

Observer are currently only available as plugins.

Plugin¶

Observer can be configured to use external plugin services.

observers:
- name: observer-0
  plugin:
    type: grpc
    addr: 127.0.0.1:8000
    tls: 
      secure: false
      serverName: example.com

addr (string, required): Plugin server address.
tls (duration, default=null): TLS encryption will be used for transmission, TLS encryption is not used by default.

Usage¶

When the status of the service changes, the status will be reported through the observer on the service. If the service has statistics enabled (enableStats option), connection and traffic statistics will also be reported.

services:
- name: service-0
  addr: ":8080"
  observer: observer-0 
  handler:
    type: http
  listener:
    type: tcp
  metadata:
    enableStats: true 

observers:
- name: observer-0
  plugin:
    type: grpc
    addr: 127.0.0.1:8000
    tls: 
      secure: false
      serverName: example.com

HTTP Plugin¶

observers:
- name: observer-0
  plugin:
    type: http
    addr: http://127.0.0.1:8000/observer

Example¶

Report Service Status

curl -XPOST http://127.0.0.1:8000/observer \
-d '{"events":[
{"kind":"service","service":"service-0","type":"status", 
"status":{"state":"running","msg":"service service-0 is running"}} 
]}'

kind (string): kind of event: service - service level, handler - handler level
service (string): service name
type (string): event types: status - service status, stats - statistics
status.state (string): status of service: running, ready, failed, closed
status.msg (string): description of status

Report Statistics

A single service will report statistics through the observer periodically (5 seconds), and stop reporting when the service's statistics is not updated (without any connection or traffic changes).

curl -XPOST http://127.0.0.1:8000/observer \
-d '{"events":[ 
{"kind":"service","service":"service-0","type":"stats", 
"stats":{"totalConns":1,"currentConns":0,"inputBytes":235,"outputBytes":632,"totalErrs":0}} 
]}'

stats.totalConns (uint64): Total number of connections handled by the service
stats.currentConns (uint64): The number of current pending connections of the service
stats.inputBytes (uint64): Total number of bytes of data received by the service
stats.outputBytes (uint64): Total number of bytes of data sent by the service
stats.totalErrs (uint64): total number of errors in service processing requests

Observer In Service Handler¶

For proxy services that support authentication (HTTP, HTTP2, SOCKS4, SOCKS5, Relay), the observer is also available to Handler.

services:
- name: service-0
  addr: ":8080"
  handler:
    type: http
    observer: observer-0
  listener:
    type: tcp

observers:
- name: observer-0
  plugin:
    addr: 127.0.0.1:8000

Observer Based On Client ID¶

Service-level observer can only be used to observe the statistics of the overall service and cannot be divided into more detailed categories for users. If you need to implement this function, you need to use a combination of the authenticator plugin and the observer plugin on the handler.

The Authenticator plugin returns the client ID after successful authentication. GOST will pass this client ID information to the Observer plugin server again.

curl -XPOST http://127.0.0.1:8000/observer \
-d '{"events":[ 
{"kind":"handler","service":"service-0","client":"user1","type":"stats", 
"stats":{"totalConns":1,"currentConns":0,"inputBytes":78,"outputBytes":574,"totalErrs":0}}, 
{"kind":"handler","service":"service-0","client":"user2","type":"stats", 
"stats":{"totalConns":1,"currentConns":0,"inputBytes":78,"outputBytes":574,"totalErrs":0}} 
]}'

client (string): client ID, generated by Authenticator