gin

README

Gin Web Framework

Gin is a web framework written in Go (Golang), based on gin.

Installation

To install Gin package, you need to install Go and set your Go workspace first.

1. The first need Go installed (version 1.11+ is required), then you can use the below Go command to install Gin.

   go get -u github.com/otel-contrib/instrumentation/github.com/gin-gonic/gin
   

2. Import it in your code:

   import "github.com/otel-contrib/instrumentation/github.com/gin-gonic/gin"
   

3. (Optional) Import net/http. This is required for example if using constants such as http.StatusOK.

   import "net/http"
   

Quick start

# assume the following codes in example.go file
cat example.go

package main

import "github.com/otel-contrib/instrumentation/github.com/gin-gonic/gin"

func main() {
    r := gin.Default()
    r.GET("/ping", func(c *gin.Context) {
        c.JSON(200, gin.H{
            "message": "pong",
        })
    })
    r.Run() // listen and serve on 0.0.0.0:8080 (for windows "localhost:8080")
}

# run example.go and visit 0.0.0.0:8080/ping (for windows "localhost:8080/ping") on browser
go run example.go

Documentation

Overview

Package gin implements a HTTP web framework called gin.

Index

• Constants
• func SetMode(value string)
• type Context
• type Engine
  • func Default(opts ...Option) *Engine
  • func New(opts ...Option) *Engine
• type H
• type HandlerFunc
  • func Logger() HandlerFunc
  • func OTel(opts ...Option) (HandlerFunc, error)
  • func Recovery() HandlerFunc
• type Option
  • func WithMeterProvider(mp metric.MeterProvider) Option
  • func WithOperationName(name string) Option
  • func WithPropagators(ps propagation.TextMapPropagator) Option
  • func WithServerName(name string) Option
  • func WithSpanNameFormatter(f SpanNameFormatter) Option
  • func WithTracerProvider(tp trace.TracerProvider) Option
• type OptionFunc
  • func (o OptionFunc) Apply(c *config)
• type SpanNameFormatter

Constants

const (
	// DebugMode indicates gin mode is debug.
	DebugMode = gin.DebugMode
	// ReleaseMode indicates gin mode is release.
	ReleaseMode = gin.ReleaseMode
	// TestMode indicates gin mode is test.
	TestMode = gin.TestMode
)

Functions

func SetMode

func SetMode(value string)

SetMode sets gin mode according to input string.

Types

type Context

type Context = gin.Context

Context is the most important part of gin. It allows us to pass variables between middleware, manage the flow, validate the JSON of a request and render a JSON response for example.

type Engine

type Engine = gin.Engine

Engine is the framework's instance, it contains the muxer, middleware and configuration settings. Create an instance of Engine, by using New() or Default()

func Default

func Default(opts ...Option) *Engine

Default returns an Engine instance with the Logger and Recovery middleware already attached. If opts is not nil, the OTel middleware will be attached.

func New

func New(opts ...Option) *Engine

New returns a new blank Engine instance without any middleware attached. If opts is not nil, the OTel middleware will be attached.

type H

type H = gin.H

H is a shortcut for map[string]interface{}

type HandlerFunc

type HandlerFunc = gin.HandlerFunc

HandlerFunc defines the handler used by gin middleware as return value.

func Logger

func Logger() HandlerFunc

Logger instances a Logger middleware that will write the logs to gin.DefaultWriter. By default gin.DefaultWriter = os.Stdout.

func OTel

func OTel(opts ...Option) (HandlerFunc, error)

OTel returns middleware that provides OpenTelemetry tracing and metrics to a gin web app.

func Recovery

func Recovery() HandlerFunc

Recovery returns a middleware that recovers from any panics and writes a 500 if there was one.

type Option

type Option interface {
	Apply(*config)
}

Option applies a configuration to the given config.

func WithMeterProvider

func WithMeterProvider(mp metric.MeterProvider) Option

WithMeterProvider specifies a meter provider to use for creating a meter. If none is specified, the global provider is used.

func WithOperationName

func WithOperationName(name string) Option

WithOperationName specifies a operation name. If none is specified, the default operation name is used.

func WithPropagators

func WithPropagators(ps propagation.TextMapPropagator) Option

WithPropagators specifies a propagators. If none is specified, the global propagator is used.

func WithServerName

func WithServerName(name string) Option

WithServerName specifies a server name. If none is specified, the default server name is used.

func WithSpanNameFormatter

func WithSpanNameFormatter(f SpanNameFormatter) Option

WithSpanNameFormatter specifies a formatter to used to format span names. If none is specified, the default SpanNameFormatter is used.

func WithTracerProvider

func WithTracerProvider(tp trace.TracerProvider) Option

WithTracerProvider specifies a tracer provider to use for creating a tracer. If none is specified, the global provider is used.

type OptionFunc

type OptionFunc func(c *config)

OptionFunc provides a convenience wrapper for simple Options that can be represented as functions.

func (OptionFunc) Apply

func (o OptionFunc) Apply(c *config)

Apply will apply the option to the config.

type SpanNameFormatter

type SpanNameFormatter func(operation string, c *gin.Context) string

SpanNameFormatter creates a custom span name from the operation and context object.