Configuring gRPC-based Telemetry
You can configure gRPC-based telemetry with the following steps.
Step 1: Create a configuration object called destination group (to add telemetry collector devices to it) like so:
CLI (network-admin@switch) > telemetry-dst-group-create name <group-name>
which you can show and delete with the following commands:
CLI (network-admin@switch) > telemetry-dst-group-show [name <group-name>]
CLI (network-admin@switch) > telemetry-dst-group-delete name <group-name>
Then add one or more collectors to the destination group using the following command:
CLI (network-admin@switch) > telemetry-dst-group-collector-add name <group-name> collector-ip <collector-ip-address> port <collector-port-number>
You can show and remove collectors from the group using the following commands:
CLI (network-admin@switch) > telemetry-dst-group-collector-show name <group-name> [collector-ip <collector-ip-address>] [port <collector-port-number>]
CLI (network-admin@switch) > telemetry-dst-group-collector-remove name <group-name> collector-ip <collector-ip-address> port <collector-port-number>
Step 2: Configure the data that you need to stream as part of a configuration object called sensor group.
Step 2.1: Create a sensor group like so:
CLI (network-admin@switch) > telemetry-sensor-group-create name <sensor-group-name>
which you can show and delete with the following commands:
CLI (network-admin@switch) > telemetry-sensor-group-show [name <sensor-group-name>]
CLI (network-admin@switch) > telemetry-sensor-group-delete name <sensor-group-name>
Step 2.2: Add sensor paths to the sensor group: a sensor path describes a valid show command supported for telemetry. In NetVisor OS release 7.0.2 the only supported sensor path is the connection-show command. You can also specify a path with filters, for example like so: connection-show src-ip 30.1.1.1.
You can add a sensor path like so:
CLI (network-admin@switch) > telemetry-sensor-group-path-add name <sensor-group-name> path <path-string>
which you can show and remove with the following commands:
CLI (network-admin@switch) > telemetry-sensor-group-path-show name <sensor-group-name> [path <path-string>]
CLI (network-admin@switch) > telemetry-sensor-group-path-remove name <sensor-group-name> path <path-string>
Note: Sensor paths used by other vendors (such as Cisco and Juniper) usually indicate a YANG path or a subset of data definitions in a YANG model. NetVisor OS release 7.0.2 does not support YANG models.
Step 3: Create a subscription object to bind a sensor group to a destination group, so that the device can start exporting data from the specified sensors paths to the specified collectors.
You can create a telemetry subscription (a binding) like so:
CLI (network-admin@switch) > telemetry-subscription-create name <subscription-name> dst-group <destination-group-name> sensor-group <sensor-group-name>
and you can specify one or more of the following options:
sample-interval <duration>: #d#h#m#s
switch-name <fabric-node-name>
switch-group <switch-group-name>
With these options, you can configure how often the telemetry data is sampled and exported. Also, you can select which switch or switch group the sampling needs to be performed on.
Note: The default sampling interval is 60 seconds. The minimum configurable sampling interval is 15 seconds.
You can show, modify or delete a subscription with the following commands:
CLI (network-admin@switch) > telemetry-subscription-show [name <subscription-name>] [dst-group <destination-group-name>] [sensor-group <sensor-group-name>] [switch-name <fabric-node-name>] [switch-group <switch-group-name>] [sample-interval <duration>]
CLI (network-admin@switch) > telemetry-subscription-delete name <subscription-name>
CLI (network-admin@switch) > telemetry-subscription-modify name <subscription-name>
and you can specify one or more of the following options:
sample-interval <duration>: #d#h#m#s
dst-group <destination-group-name>
sensor-group <sensor-group-name>
switch-name <fabric-node-name>
switch-group <switch-group-name>
Note: NetVisor OS release 7.0.2 supports a maximum of 10 subscriptions.
Step 4: Enable (or disable) the gRPC service and configure any parameters such as TLS secure transport:
CLI (network-admin@switch) > telemetry-grpc-settings-modify
you can specify one or more of the following options:
enable-service| disable-service
tls-enable|no-tls-enable
no-tls-enable corresponds to insecure communication.
You can then display the settings:
CLI (network-admin@switch) > telemetry-grpc-settings-show
Note: By default, the gRPC telemetry service uses TLS credentials and looks for a client certificate at this location: /var/nvos/cert/grpc/ca_cert.pem. So in NetVisor OS release 7.0.2 certificate management is manual.
Note: All gRPC telemetry commands are locally scoped. It is sufficient to enable telemetry services on one fabric node.
Example of Configuration:
1. Configure destination groups and collectors:
CLI (network-admin@switch) > telemetry-dst-group-create name dg1
CLI (network-admin@switch) > telemetry-dst-group-collector-add name dg1 collector-ip 192.168.99.20 port 50051
CLI (network-admin@switch) > telemetry-dst-group-show
switch name
------ ----
switch dg1
CLI (network-admin@switch) > telemetry-dst-group-collector-show
switch name collector-ip port
------ ---- ------------ -----
switch dg1 192.168.99.20 50051
2. Configure sensor groups and sensor paths:
CLI (network-admin@switch) > telemetry-sensor-group-create name sg1
CLI (network-admin@switch) > telemetry-sensor-group-path-add name sg1 path "connection-show"
CLI (network-admin@switch) > telemetry-sensor-group-show
switch name
------ ----
switch sg1
CLI (network-admin@switch) > telemetry-sensor-group-path-show
switch name path
------ ---- ---------------
switch sg1 connection-show
Other examples for the sensor path string can be:
connection-show src-ip x.x.x.x
connection-show within-last 15m
Note: In the sensor path string you cannot specify any format or switch argument such as in this invalid examples: connection-show format field1,field2 or switch switch1 connection-show .
3. Configure subscriptions:
CLI (network-admin@switch) > telemetry-subscription-create name sub1 dst-group dg1 sensor-group sg1 sample-interval 1m
CLI (network-admin@switch) > telemetry-subscription-show
switch name dst-group sensor-group sample-interval
------ ---- --------- ------------ ---------------
switch sub1 dg1 sg1 1m
To stream telemetry data of a specific switch only (instead of all fabric nodes), specify the switch name in the configuration, as shown below:
CLI (network-admin@switch) > telemetry-subscription-create name sub1 dst-group dg1 sensor-group sg1 switch-name switch1
CLI (network-admin@switch) > telemetry-subscription-show
switch name dst-group sensor-group switch-name sample-interval
------ ---- --------- ------------ ----------- ---------------
switch sub2 dg1 sg1 switch1 60s
To stream telemetry data from a group of switches, you can specify a switch group as shown below:
CLI (network-admin@switch) > switch-group-create name sw_grp_1 description "telemetry switch group"
CLI (network-admin@switch) > switch-group-member-add name sw_grp_1 member switch1,switch2
CLI (network-admin@switch) > switch-group-member-show
switch name member
------ -------- -------
switch sw_grp_1 switch1
switch sw_grp_1 switch2
CLI (network-admin@switch) > telemetry-subscription-modify name sub1 dst-group dg1 switch-group sw_grp_1
CLI (network-admin@switch) > telemetry-subscription-show
switch name dst-group sensor-group switch-group sample-interval
------ ---- --------- ------------ ------------ ---------------
switch sub1 dg1 sg1 sw_grp_1 60s
4. Enable the gRPC telemetry service:
CLI (network-admin@switch) > telemetry-grpc-settings-modify enable-service
CLI (network-admin@switch) > telemetry-grpc-settings-show
enable-service: yes
state: enabled
Developing a Collector Application
The gRPC telemetry data from a NetVisor OS switch can be sent to a collector that can be a tool developed in house or a commercial data monitoring application.
To create your own tool, obtain the nvos.proto file for NetVisor OS so that the collector can receive and resolve the data obtained from the network device.
Utilize any of the gRPC-supported languages (e.g., C++, Java, python, Go, etc.) to develop the collector application. The example below uses the Go language.
Generate the server code from the nvos.proto file using the protocol buffer compiler protoc:
protoc --go_out=. --go_opt=paths=source_relative --go-grpc_out=. \ --go-grpc_opt=paths=source_relative nvos.proto
Import the generated package:
import (
pb "path the nvos.proto generate directory"
)
Define the struct to implement the generated nvos_proto.TelemetryServer interface:
type server struct {
pb.UnimplementedTelemetryServer
}
Implement the interface method to read the streamed connections and to return a response:
func (s *server) PushConnections(stream pb.Telemetry_PushConnectionsServer) error {
for {
conn, err := stream.Recv()
if err == io.EOF {
// Close the connection and return the response to the client
return stream.SendAndClose(&pb.Response{
Status: pb.Response_SUCCESS,
Message: "",
})
}
if err != nil {
//Handle any possible errors
}
log.Printf("Connection Data received: %v", conn)
//The data received here can be forwarded to any database or monitoring tool
}
}
Then start the server:
//specify the address to listen to
lis, err := net.Listen("tcp", ":<port no>")
if err != nil {
log.Fatalf("failed to listen: %v", err)
}
//Load the credentials.
creds, err := credentials.NewServerTLSFromFile("server_cert.pem", "server_key.pem")
// create grpc server
s = grpc.NewServer(grpc.Creds(creds))
pb.RegisterTelemetryServer(s, &server{})
log.Printf("server listening at %v", lis.Addr())
// and start
if err := s.Serve(lis); err != nil {
log.Fatalf("failed to serve: %v", err)
}