OpenCensus Stats implementation (#220)

Initial version of OpenCensus Stats and Tags API

Also:
- PHP 7.3 testing & support
- Fix issue with test filenames and phpize --clean (don't allow .php in ext dir)
- DaemonClient (Go) for transporting OpenCensus data from PHP to OpenCensus Service
- Extension update to include low level daemon client offloading data transmission from request path
- Removes support for PHP 5.6 and PHP 7.0 
- Fixed Symfony test 
- Fixed Wordpress test (they have a new and different default theme generating different calls)
- Added Dockerfile for Daemon Service
- Added Dockerfile for OpenCensus enabled PHP7.3-Apache (for demo/testing purposes)

Author: basvanbeek

.circleci/config.yml

@@ -77,32 +77,6 @@ unit-config: &unit-config
 
 version: 2
 jobs:
-  php56:
-    <<: *unit-config
-    docker:
-      - image: circleci/php:5.6-node
-    environment:
-      RUN_EXTENSION_TESTS: 0
-      SUDO_CMD: "sudo"
-
-  php56-zts:
-    <<: *unit-config
-    docker:
-      - image: circleci/php:5.6-zts-node
-    environment:
-      RUN_EXTENSION_TESTS: 0
-      SUDO_CMD: "sudo"
-
-  php70:
-    <<: *unit-config
-    docker:
-      - image: circleci/php:7.0-node
-
-  php70-zts:
-    <<: *unit-config
-    docker:
-      - image: circleci/php:7.0-zts-node
-
   php71:
     <<: *unit-config
     docker:
@@ -123,15 +97,15 @@ jobs:
     docker:
       - image: circleci/php:7.2-zts-node
 
-  php70-32bit:
+  php73:
     <<: *unit-config
     docker:
-      - image: gcr.io/php-stackdriver/php70-32bit
-    environment:
-      TEST_PHP_ARGS: -q
-      REPORT_EXIT_STATUS: 1
-      RUN_EXTENSION_TESTS: 1
-      SUDO_CMD: ""
+      - image: circleci/php:7.3-node
+
+  php73-zts:
+    <<: *unit-config
+    docker:
+      - image: circleci/php:7.3-zts-node
 
   php71-32bit:
     <<: *unit-config
@@ -246,15 +220,12 @@ workflows:
   version: 2
   units:
     jobs:
-      - php56
-      - php56-zts
-      - php70
-      - php70-zts
       - php71
       - php71-zts
       - php72
       - php72-zts
-      - php70-32bit
+      - php73
+      - php73-zts
       - php71-32bit
       - php71-debug
       - integration

.gitignore

@@ -1,8 +1,9 @@
 # OS X
 .DS_Store
 
-# VSCode
+# VSCode and other IDE's
 .vscode/
+.idea/
 
 # Composer
 build/

composer.json

@@ -7,11 +7,15 @@
         {
             "name": "Jeff Ching",
             "email": "chingor@google.com"
+        },
+        {
+            "name": "Bas van Beek",
+            "email": "bas.vanbeek@gmail.com"
         }
     ],
     "minimum-stability": "stable",
     "require": {
-        "php": ">=5.6",
+        "php": ">=7.1",
         "ramsey/uuid": "~3",
         "psr/log": "^1.0",
         "psr/cache": "^1.0",

daemon/Dockerfile

@@ -0,0 +1,35 @@
+#
+# build oc-daemon binary
+#
+
+FROM golang:alpine as builder
+ENV GOPATH /go
+
+RUN apk update && apk add --no-cache git ca-certificates tzdata make && update-ca-certificates
+
+RUN adduser -D -g '' opencensus
+
+COPY . $GOPATH/src/github.com/census-instrumentation/opencensus-php/daemon
+WORKDIR $GOPATH/src/github.com/census-instrumentation/opencensus-php/daemon
+
+RUN mkdir /newtmp && chown opencensus /newtmp && chmod 777 /newtmp
+
+RUN CGO_ENABLED=0 make build-linux
+
+#
+# build image from scratch
+#
+
+FROM scratch
+COPY --from=builder /usr/share/zoneinfo /usr/share/zoneinfo
+COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
+COPY --from=builder /etc/passwd /etc/passwd
+COPY --from=builder /etc/group /etc/group
+COPY --from=builder /go/src/github.com/census-instrumentation/opencensus-php/daemon/build/oc-daemon-linux /usr/bin/oc-daemon
+COPY --chown=opencensus:opencensus --from=builder /newtmp /tmp
+
+VOLUME /tmp
+
+USER opencensus
+
+ENTRYPOINT ["/usr/bin/oc-daemon"]

daemon/Makefile

@@ -0,0 +1,38 @@
+BUILD        := $(shell git describe --long --tags)
+BUILD_DATE   := $(shell date -u +'%Y-%m-%d %H:%M:%S')
+
+ifeq ($(BUILD),)
+	BUILD := "v0.0.0"
+endif
+
+.PHONY: test
+test:
+	go test -v -race -cover ./...
+
+.PHONY: lint
+lint:
+	golint ./...
+
+.PHONY: vet
+vet:
+	go vet ./...
+
+build: build-linux build-darwin build-windows
+
+build-linux:
+	GO111MODULE=on GOOS=linux   GOARCH=amd64 go build -i -ldflags "-X \"main.buildVersion=${BUILD} (Linux)\"   -X \"main.buildDate=${BUILD_DATE}\"" -o build/oc-daemon-linux ./cmd
+
+build-darwin:
+	GO111MODULE=on GOOS=darwin  GOARCH=amd64 go build -i -ldflags "-X \"main.buildVersion=${BUILD} (OS X)\"    -X \"main.buildDate=${BUILD_DATE}\"" -o build/oc-daemon-osx   ./cmd
+
+build-windows:
+	GO111MODULE=on GOOS=windows GOARCH=amd64 go build -i -ldflags "-X \"main.buildVersion=${BUILD} (Windows)\" -X \"main.buildDate=${BUILD_DATE}\"" -o build/oc-daemon.exe   ./cmd
+
+docker:
+	docker build --rm --no-cache -f Dockerfile -t oc-daemon . 
+
+clean:
+	@rm -rf build
+
+.PHONY: all
+all: clean vet lint test build

daemon/README.md

@@ -0,0 +1,194 @@
+# OpenCensus PHP Daemon Service
+
+The Daemon service allows the OpenCensus PHP library to export stats and traces 
+over a local unix socket or windows named pipe. The Daemon will then take care 
+of transporting the information to the OpenCensus Agent over gRPC.
+
+By using the Daemon in between the OpenCensus PHP library and OpenCensus Agent 
+we avoid the need of injecting the gRPC extension into PHP, even making it 
+possible to run OpenCensus without the need of installing any extension.
+
+## Daemon Protocol
+
+Communication between OpenCensus PHP and OpenCensus PHP Daemon service is 
+handled by using a simple protocol. The protocol is designed to expect partial 
+message delivery allowing such a message to be discarded and proceed to ingest 
+the next message. This situation can occur when using the PHP user land 
+implementation of the Daemon client as it uses non blocking sockets with a 
+settable maximum message delivery time to not hold up the PHP request critical 
+path.
+
+A protocol message consists of a header and the message payload.
+
+All number representations (UVarint, Float64, padded Float32, Integer) are sent 
+in big endian (network) byte order.
+
+### Protocol header
+
+| name           | type    | size  | comment                                                   
+|----------------|---------|------:|---------
+| SOM            | Bytes   |     4 | Start of message "\x00\x00\x00\x00"
+| Message Type   | Byte    |     1 | Message Type
+| Sequence Nr.   | UVarInt |  1-10 |
+| Process ID     | UVarInt |  1-10 |
+| Thread ID      | UVarInt |  1-10 | Will be 0 for non ZTS deployments
+| StartTime      | Float*  |     8 | Unix timestamp with fraction: Float64 or padded Float32 (`\x00\x00 + Float32 + \x00\x00`)
+| Message Length | UVarInt |  1-10 | **TODO:** identify a maximum allowed message length. This will most likely be dictated by Span exports.
+
+**Note:** PHP can't guarantee the size of a Float when exporting it out. It will 
+either be 64 bit or 32 bit depending on the platform. If StartTime is padded 
+with `\x00\x00` on both sides we know that all exported floats will be of 32 bit 
+length. If StartTime is a 64bit float, all remaining Float values will be 
+exported as 64 bit.
+
+By use of UVarInt we have a variable length Header. This allows the header to be 
+as small as 17 bytes in the most optimistic circumstances and as large as 53 in 
+the most pessimistic ones.
+
+### Data Types
+
+Our messages allow for the following data types and their encoding:
+
+#### Byte
+Single unsigned byte holding value between 0 and 255.
+
+#### Float
+Depending on the PHP runtime a float value will be either 64 or 32 bit in 
+resolution. All floats are big endian (network) byte order encoded. To identify
+the size of the float, the Daemon implementation inspects the StartTime field in 
+the header. If this field is `\x00\x00` padded on both sides, we're dealing with 
+32 bit floats.
+
+#### String
+Strings are prefixed by a UVarInt indicating string length immediately followed 
+by the unterminated binary string payload. Empty strings are allowed.
+
+#### Array
+Arrays are prefixed by a UVarInt indicating the array item count immediately 
+followed by the array items. Empty arrays are allowed.
+
+### Protocol message types
+
+The following message types and their contents have been defined.
+
+#### MSG_PROC_INIT
+**Message Type: 1**
+
+Sent to the Daemon when a new PHP Process spawns. (only sent if using the 
+OpenCensus Extension).
+
+**TODO**: payload to be determined 
+
+#### MSG_PROC_SHUTDOWN
+**Message Type: 2**
+
+Sent to the Daemon when a PHP Process is shut down. (only sent if using the 
+OpenCensus Extension).
+
+**TODO**: payload to be determined 
+
+#### MSG_REQ_INIT
+**Message Type: 3**
+
+Sent to the Daemon when a new PHP Request is received.
+
+| field              | type    | comment
+|--------------------|---------|---------
+| Protocol Version   | Byte    | Daemon Protocol Version (currently 1 only)
+| PHP Version        | String  |
+| Zend Version       | String  |
+
+
+#### MSG_REQ_SHUTDOWN
+**Message Type: 4**
+
+Sent to the Daemon when a PHP Request ends.
+
+| field | type | comment
+|-------|------|---------
+|     - |    - | no message payload
+
+#### MSG_TRACE_EXPORT 
+**Message Type: 20**
+
+A collection of Spans ready to be exported.
+
+**TODO:** Currently uses a JSON encoded array of spans. Span payload is
+subject to change.
+
+#### MSG_MEASURE_CREATE
+**Message Type: 40**
+
+Measure Create request.
+
+| field              | type    | comment
+|--------------------|---------|---------
+| MeasureType        | Byte    | 1 = IntMeasure, 2 = FloatMeasure
+| Name               | String  |
+| Description        | String  |
+| Unit               | String  |
+
+#### MSG_VIEW_REPORTING_PERIOD
+**Message Type: 41**
+
+Reporting Period adjustment request.
+
+| field              | type    | comment
+|--------------------|---------|---------
+| Interval           | Float   | Interval in seconds
+
+#### MSG_VIEW_REGISTER
+**Message Type: 42**
+
+Register View request.
+
+| field              | type              | comment
+|--------------------|-------------------|---------
+| Views              | Array of **View** | Array of Views to Register.
+
+View Type:
+
+| field              | type            | comment
+|--------------------|-----------------|---------
+| View Name          | String          |
+| View Description   | String          |
+| Tag Keys           | Array of String | Array of TagKey values.
+| Measure Name       | String          |
+| Aggregation Type   | Byte            | 0 = None, 1 = Count, 2 = Sum, 3 = Distribution, 4 = Last Value
+| Bucket Boundaries* | Array of Float  | Only sent for the Distribution aggregation type
+
+
+#### MSG_VIEW_UNREGISTER
+**Message Type: 43**
+
+Unregister View request.
+
+| field              | type            | comment
+|--------------------|-----------------|---------
+| View Names         | Array of String | Array holding names of Views to Unregister
+
+#### MSG_STATS_RECORD
+**Message Type: 44**
+
+Stats Record request.
+
+| field              | type                     | comment
+|--------------------|--------------------------|---------
+| Measurements       | Array of **Measurement** | Measurements to record
+| Tags               | Array of **KeyValue**  | Tag kv pairs
+| Attachments        | Array of **KeyValue**  | Exemplar attachment kv pairs
+
+Measurement Type:
+
+| field        | type   | comment
+|--------------|--------|---------
+| Name         | String |
+| Measure Type | Byte   | 1 = IntMeasure, 2 = FloatMeasure
+| Value        | Float  | Value is always transported as Float
+
+KeyValue Type:
+
+| field | type   | comment
+|-------|--------|---------
+| Key   | String |
+| Value | String |