hmetrics: Add license/headers, make endpoint specifyable.

LICENSE.txt

@@ -0,0 +1,27 @@
+Copyright (c) 2018, Salesforce.com, Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice, this
+list of conditions and the following disclaimer in the documentation and/or
+other materials provided with the distribution.
+
+* Neither the name of Salesforce.com nor the names of its contributors may be
+used to endorse or promote products derived from this software without specific
+prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

hmetrics/doc.go

@@ -1,5 +1,18 @@
+/* Copyright (c) 2018 Salesforce
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root  or https://opensource.org/licenses/BSD-3-Clause
+ */
+
 /*
-package hmetrics is a self-contained client for heroku Go runtime metrics.
-*/
+Package hmetrics is a self-contained client for Heroku Go runtime metrics.
+
+Typical usage is through the `github.com/heroku/x/hmetrics/onload` package
+imported like so:
 
+  import _ "github.com/heroku/x/hmetrics/onload"
+
+You can find more information about Heroku Go runtime metrics here:
+https://devcenter.heroku.com/articles/language-runtime-metrics-go
+*/
 package hmetrics

hmetrics/example/advanced/main.go

@@ -1,3 +1,8 @@
+/* Copyright (c) 2018 Salesforce
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root  or https://opensource.org/licenses/BSD-3-Clause
+ */
 package main
 
 import (
@@ -9,22 +14,19 @@ import (
 	"github.com/heroku/x/hmetrics"
 )
 
-type fataler interface {
-	Fatal() bool
-}
-
 func main() {
 	ctx, cancel := context.WithCancel(context.Background())
 	defer cancel()
 
-	eh := func(err error) error {
-		log.Println("Error reporting metrics to heroku:", err)
-		return nil
-	}
-
 	go func() {
-		for {
-			if err := hmetrics.Report(ctx, eh); err != nil {
+		type fataler interface {
+			Fatal() bool
+		}
+		for { // try again and again on non fatal errors
+			if err := hmetrics.Report(ctx, hmetrics.DefaultEndpoint, func(err error) error {
+				log.Println("Error reporting metrics to heroku:", err)
+				return nil
+			}); err != nil {
 				if f, ok := err.(fataler); ok && f.Fatal() {
 					log.Fatal(err)
 				}

hmetrics/example/basic/main.go

@@ -1,3 +1,8 @@
+/* Copyright (c) 2018 Salesforce
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root  or https://opensource.org/licenses/BSD-3-Clause
+ */
 package main
 
 import (
@@ -10,7 +15,7 @@ import (
 
 func main() {
 	// Don't care about canceling or errors
-	go func() { hmetrics.Report(context.Background(), nil) }()
+	go hmetrics.Report(context.Background(), hmetrics.DefaultEndpoint, nil)
 
 	port := os.Getenv("PORT")
 	if port == "" {

hmetrics/example/onload/main.go

@@ -1,3 +1,8 @@
+/* Copyright (c) 2018 Salesforce
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root  or https://opensource.org/licenses/BSD-3-Clause
+ */
 package main
 
 import (

hmetrics/examples_test.go

@@ -0,0 +1,64 @@
+/* Copyright (c) 2018 Salesforce
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root  or https://opensource.org/licenses/BSD-3-Clause
+ */
+package hmetrics_test
+
+import (
+	"context"
+	"log"
+	"net/http"
+	"os"
+
+	"github.com/heroku/x/hmetrics"
+)
+
+func ExampleReport_basic() {
+	// Don't care about canceling or errors
+	go hmetrics.Report(context.Background(), hmetrics.DefaultEndpoint, nil)
+
+	port := os.Getenv("PORT")
+	if port == "" {
+		port = "8080"
+	}
+	http.ListenAndServe(":"+port, nil)
+}
+
+func ExampleReport_logging() {
+	go func() {
+		if err := hmetrics.Report(context.Background(), hmetrics.DefaultEndpoint, func(err error) error {
+			log.Println("Error reporting metrics to heroku:", err)
+			return nil
+		}); err != nil {
+			log.Fatal("Error starting hmetrics reporting:", err)
+		}
+	}()
+}
+func ExampleReport_advanced() {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	go func() {
+		type fataler interface {
+			Fatal() bool
+		}
+		for { // try again and again on non fatal errors
+			if err := hmetrics.Report(ctx, hmetrics.DefaultEndpoint, func(err error) error {
+				log.Println("Error reporting metrics to heroku:", err)
+				return nil
+			}); err != nil {
+				if f, ok := err.(fataler); ok && f.Fatal() {
+					log.Fatal(err)
+				}
+				log.Println(err)
+			}
+		}
+	}()
+
+	port := os.Getenv("PORT")
+	if port == "" {
+		port = "8080"
+	}
+	http.ListenAndServe(":"+port, nil)
+}

hmetrics/hmetrics.go

@@ -1,12 +1,19 @@
+/* Copyright (c) 2018 Salesforce
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root  or https://opensource.org/licenses/BSD-3-Clause
+ */
 package hmetrics
 
 import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"net/http"
+	"net/url"
 	"os"
 	"runtime"
 	"sync"
@@ -59,36 +66,48 @@ var (
 	started bool
 )
 
-// Report go metrics to Heroku until the context is canceled.
+// Report go metrics to the endpoint until the context is canceled.
 //
 // Only one call to the ErrHandler will happen at a time. Metrics can be dropped
 // or delayed if a call to ErrHandler takes longer than the reprting interval.
 // Processing of metrics continues if the ErrHandler returns nil, but aborts if
 // the ErrHandler itself returns an error. It is safe to pass a nil ErrHandler.
 //
-// Report is safe for concurrent usage, but calling it more than once w/o
-// canceling the context returns an AlreadyStarted error. This is to ensure that
-// metrics aren't duplicated. Report can be called again to restart reporting
-// after the context is canceled.
-func Report(ctx context.Context, ef ErrHandler) error {
+// Report is safe for concurrent usage, but calling it again w/o canceling the
+// context passed previously returns an AlreadyStarted error. This is to ensure
+// that metrics aren't duplicated. Report can be called again to restart
+// reporting after the context is canceled.
+func Report(ctx context.Context, endpoint string, ef ErrHandler) error {
+	if err := startable(endpoint); err != nil {
+		return err
+	}
+
+	report(ctx, &http.Client{Timeout: 20 * time.Second}, endpoint, errorHandler(ef))
+
+	mu.Lock()
+	defer mu.Unlock()
+	started = false
+	return nil
+}
+
+// err if not startable, otherwise start
+func startable(endpoint string) error {
 	mu.Lock()
+	defer mu.Unlock()
 	if started {
-		mu.Unlock()
 		return AlreadyStarted{}
 	}
-	endpoint := DefaultEndpoint
 	if endpoint == "" {
-		mu.Unlock()
-		return HerokuMetricsURLUnset{}
+		return &url.Error{
+			Op:  "Empty",
+			URL: endpoint,
+			Err: errors.New("Empty string"),
+		}
+	}
+	if _, err := url.Parse(endpoint); err != nil {
+		return err
 	}
 	started = true
-	mu.Unlock()
-
-	report(ctx, &http.Client{Timeout: 20 * time.Second}, endpoint, errorHandler(ef))
-
-	mu.Lock()
-	started = false
-	mu.Unlock()
 	return nil
 }
 

hmetrics/hmetrics_test.go

@@ -0,0 +1,15 @@
+/* Copyright (c) 2018 Salesforce
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root  or https://opensource.org/licenses/BSD-3-Clause
+ */
+package hmetrics
+
+import "testing"
+
+func TestStartable_EmptyEndpoint(t *testing.T) {
+	err := startable("")
+	if err == nil {
+		t.Errorf("Expected an error, but got nil instead")
+	}
+}

hmetrics/onload/init.go

@@ -1,27 +1,49 @@
+/* Copyright (c) 2018 Salesforce
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root  or https://opensource.org/licenses/BSD-3-Clause
+ */
+
 /*
-package onload automatically starts up the hmetrics reporting.
+Package onload automatically starts hmetrics reporting, ignoring errors and
+retrying reporting, backing off in 10 second increments.
 
-Use this package when you don't care about shutting down them metrics reporting or being notified of any reporting
-errors.
+Use this package when you don't care about stopping reporting, specifying the
+endpoint, or being notified of any reporting errors.
 
 usage:
 
 import (
 	_ "github.com/heroku/x/hmetrics/onload"
 )
 
-*/
+See github.com/heroku/x/hmetrics documentation for more info about Heroku Go
+metrics and advanced usage.
 
+*/
 package onload
 
 import (
 	"context"
+	"time"
 
 	"github.com/heroku/x/hmetrics"
 )
 
+const (
+	interval = 10
+)
+
 func init() {
 	go func() {
-		hmetrics.Report(context.Background(), nil)
+		var backoff int64
+		for backoff = 1; ; backoff++ {
+			start := time.Now()
+			hmetrics.Report(context.Background(), hmetrics.DefaultEndpoint, nil)
+			if time.Since(start) > 5*time.Minute {
+				backoff = 1
+			}
+			time.Sleep(time.Duration(backoff*interval) * time.Second)
+		}
 	}()
 }