Skip to content

Commit

Permalink
Merge pull request #5 from ns1/bb-payload-v6
Browse files Browse the repository at this point in the history
Implemented BulkBeacon Protobuf Definitions version 2
  • Loading branch information
antoniovl authored Apr 21, 2021
2 parents 5f4c10d + 1a59a5f commit eb65248
Show file tree
Hide file tree
Showing 10 changed files with 591 additions and 50 deletions.
47 changes: 38 additions & 9 deletions Makefile
Original file line number Diff line number Diff line change
@@ -1,16 +1,45 @@
BUIlD_BASE_DIR := build
GEN_BASE_DIR := gen
# Copyright 2021 NSONE, Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http:#www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

BUILD_BASE_DIR := build
PROTO_BASE_DIR := proto

all: examples
PB_DIR := proto/bulkbeacon
PB_OUT := pkg/bulkbeacon
GRPC_OUT := pkg/bulkbeacon
PKG_PREFIX := github.com/ns1/pulsar-rum
BUILD := ./build.sh

all: bulkbeacon_v1 bulkbeacon_v2

V1_GO_FILES := $(PB_OUT)/v1/bulkbeacon.pb.go $(PB_OUT)/v1/bulkbeacon_grpc.pb.go
.PHONY: bulkbeacon_v1
bulkbeacon_v1: $(V1_GO_FILES)
$(V1_GO_FILES): $(PB_DIR)/v1/bulkbeacon.proto
$(BUILD) v1
mkdir -p $(BUILD_BASE_DIR)
go build -o $(BUILD_BASE_DIR)/grpc_example_client_v1 cmd/example_client_v1/main.go

.PHONY: examples
examples:
mkdir -p $(GEN_BASE_DIR)/bulkbeacon/v1 $(BUIlD_BASE_DIR)
protoc -I=$(PROTO_BASE_DIR) $(PROTO_BASE_DIR)/bulkbeacon/v1/bulkbeacon.proto --go_out=plugins=grpc:$(GEN_BASE_DIR)
go build -o $(BUIlD_BASE_DIR)/grpc_example_client cmd/example_client/grpc_example_client.go
V2_GO_FILES := $(PB_OUT)/v2/bulkbeacon.pb.go $(PB_OUT)/v2/bulkbeacon_grpc.pb.go
.PHONY: bulkbeacon_v2
bulkbeacon_v2: $(V2_GO_FILES)
$(V2_GO_FILES): $(PB_DIR)/v2/bulkbeacon.proto
$(BUILD) v2
mkdir -p $(BUILD_BASE_DIR)
go build -o $(BUILD_BASE_DIR)/grpc_example_client_v2 cmd/example_client_v2/main.go

.PHONY: clean
clean:
rm -rf $(GEN_BASE_DIR) $(BUIlD_BASE_DIR)
rm -rf $(BUILD_BASE_DIR) $(PB_OUT)/v2 $(PB_OUT)/v1

53 changes: 40 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,27 +3,42 @@ Pulsar Real User Monitoring (RUM)

> This project is in [active development](https://github.com/ns1/community/blob/master/project_status/ACTIVE_DEVELOPMENT.md).
Utilities for working with Pulsar RUM.
Utilities and sample programs for Pulsar RUM.


Bulk Beacons
------------

A method to send performance data to Pulsar in bulk. gRPC and HTTP+JSON are
supported. See comments in the `bulkbeacon.proto` file for how to structure
messages.
supported.

See comments in the `bulkbeacon.proto` definition file for how to structure messages.
Depending on the version of the Bulk Beacon ingestion, you will have to look at its respective
directory (mentioned below in the `Getting started with gRPC` section).

### Versions

We currently support two formats for gRPC and HTTP+JSON for Bulk Beacons. Each one can be
found in `proto/bulkbeacon/{version}/bulkbeacon.proto`, with `version` taking values
of `v1` and `v2`.

Version 1 was the first formal release of the Bulk Beacon ingestion, and version 2
supports a new feature for multiple metrics. For more information, please contact
your Customer Success Representative.

### Getting started with gRPC

1. Copy the desired version of
[bulkbeacon.proto](https://github.com/ns1/pulsar-rum/tree/master/proto/bulkbeacon)
into your project. Use your preferred method of building gRPC clients from that
`.proto` file.
1. Copy the desired version of `bulkbeacon.proto` from either
[https://github.com/ns1/pulsar-rum/tree/master/proto/bulkbeacon/v1](https://github.com/ns1/pulsar-rum/tree/master/proto/bulkbeacon/v1)
or [https://github.com/ns1/pulsar-rum/tree/master/proto/bulkbeacon/v2](https://github.com/ns1/pulsar-rum/tree/master/proto/bulkbeacon/v1)
into your project. Use your preferred method of building gRPC clients from that `.proto` file.
2. Use `g.ns1p.net:443` as the service's target address.
3. Enable TLS on your gRPC transport.
4. Add your NS1 API key. Please check the examples to see how to add the authentication key.

See the [example Golang client](https://github.com/ns1/pulsar-rum/blob/master/cmd/example_client/grpc_example_client.go)
for more details. Additionally, check out https://grpc.io/ for more examples & details
See the [v1 example Golang client](https://github.com/ns1/pulsar-rum/blob/master/cmd/example_client_v1/main.go)
or the [v2 example Golang client](https://github.com/ns1/pulsar-rum/blob/master/cmd/example_client_v2/main.go)
for more details. Additionally, check out https://grpc.io/ for more information
regarding dependencies and compiling for other languages.

### Getting started with HTTP+JSON
Expand All @@ -36,16 +51,28 @@ serialize protocol buffer objects to JSON. Some information is available on
[the protocol buffer docs](https://github.com/protocolbuffers/protobuf/blob/master/docs/third_party.md)
page.


Building the examples
---------------------

The examples can be built executing (from the `pulsar-rum` directory) with:
The examples can be built executing several commands from the `pulsar-rum` directory.

To build both examples, execute:
```sh
$ make examples
$ make
```

If you want to build a specific version, execute:
```shell
$ make bulkbeacon_v1
```
or
```shell
$ make bulkbeacon_v2
```

You can find the binaries on the `build/` directory.

If unsure, reach out with any question you could have.

Contributing
------------
Expand All @@ -57,7 +84,7 @@ for more information.
License
-------

Copyright (C) 2020, NSONE, Inc.
Copyright (C) 2021, NSONE, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
Expand Down
62 changes: 62 additions & 0 deletions build.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
#!/bin/bash
# Copyright 2021 NSONE, Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http:#www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# Utility for generating protobuf and gRPC artifacts for the Bulk Beacon service.

valid_versions="v1 v2"
PB_DIR="proto/bulkbeacon"
PB_OUT="pkg/bulkbeacon"
PKG_PREFIX="github.com/ns1/pulsar-rum"

function validate_version() {
for i in $valid_versions; do
if [[ $i == $1 ]]; then
echo "Bulk Beacon: ${i} is a valid version."
return
fi
done
echo "Error: '$1' is not a valid Bulk Beacon version."
exit 1
}

function build() {
v="${1}"
proto_file="${PB_DIR}/${v}/bulkbeacon.proto"
proto_pkg="${PB_OUT}/${v}"
opt_m="M${proto_file}=${PKG_PREFIX}/${PB_OUT}/${v}"
echo "Bulk Beacon: Building ${proto_file}"
mkdir -p "${proto_pkg}"
protoc --go_out=. --go_opt="${opt_m}" --go_opt="module=${PKG_PREFIX}" \
--go-grpc_out=. --go-grpc_opt="${opt_m}" --go-grpc_opt="module=${PKG_PREFIX}" "${proto_file}"
}

function usage() {
echo -n "Utility for generating protobuf and gRPC artifacts for the Pulsar Bulk "
echo "Beacon Service."
echo "(c) NS1 Inc."
echo "Usage:"
echo "$0 <v1|v2>"
}

if [[ $# != 1 ]]; then
usage
exit 1
elif [[ $1 == "-h" || $1 == "--help" ]]; then
usage
exit 1
fi

validate_version "${1}"
build "${1}"
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
// Copyright 2020 NSONE, Inc.
// Copyright 2021 NSONE, Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
Expand Down Expand Up @@ -26,17 +26,24 @@ import (
"google.golang.org/grpc"
"google.golang.org/grpc/credentials"

pb "pulsar-rum/gen/bulkbeacon/v1"
"github.com/ns1/pulsar-rum/pkg/bulkbeacon"
pb "github.com/ns1/pulsar-rum/pkg/bulkbeacon/v1"
)

var (
appID = "__appID__" // FIXME: Your AppID here.
jobID = "__jobID__" // FIXME: Your JobID here.
authKey = "__authKey__" // FIXME: Your NS1 API key here.
)

var beacons = &pb.Beacons{
Beacons: []*pb.Beacon{
{
Appid: "__APPID__", // FIXME: Your AppID here.
Appid: appID, // FIXME: Your AppID here.
Measurements: []*pb.Measurement{
{
Attribution: &pb.Attribution{
Jobid: "__JOBID__", // FIXME: Your JobID here.
Jobid: jobID, // FIXME: Your JobID here.
Location: &pb.Location{
GeoCountry: "GB",
Asn: 2856,
Expand All @@ -58,25 +65,6 @@ var beacons = &pb.Beacons{
},
}

// auth it's a simple structure to manage the authentication. It implements
// grpc.PerRPCCredentials interface.
type auth struct {
key string
}

// GetRequestMetadata sets the authentication key into the metadata map.
func (a auth) GetRequestMetadata(ctx context.Context, in ...string) (map[string]string, error) {
m := map[string]string{
"X-NSONE-Key": a.key,
}
return m, nil
}

// RequireTransportSecurity must return true if we are using TLS.
func (a auth) RequireTransportSecurity() bool {
return true
}

func main() {

address := "g.ns1p.net:443"
Expand All @@ -89,7 +77,7 @@ func main() {
fmt.Printf("Go version: %s\n", runtime.Version())

// Setup authentication
auth := auth{key: "__YOUR_NS1_API_KEY__"}
auth := bulkbeacon.NewAuth(authKey)

// Set up gRPC connection
log.Println("dialing")
Expand Down
Loading

0 comments on commit eb65248

Please sign in to comment.