github.com/pyroscope-io/pyroscope@v0.37.3-0.20230725203016-5f6947968bd0/examples/golang-pull/consul/README.md (about)

     1  # Pyroscope pull mode and Consul Discovery
     2  
     3  This example demonstrates how Pyroscope can be used to scrape pprof profiles from services discovered with [Consul](https://developer.hashicorp.com/consul/docs/intro).
     4  
     5  The example is a docker compose that consists of:
     6   - Pyroscope server
     7   - Single node Consul cluster
     8   - Demo application that is being profiled
     9  
    10  Run the demo:
    11  ```shel
    12  docker-compose up --build -d
    13  ```
    14  
    15  Now that everything is set up, you should be able to browse profiling data via [Pyroscope UI](http://localhost:4040)
    16  and find the demo application called `test-service`.
    17  
    18  In the example, our demo application registers itself using Consul API. In practice, the exact service registration
    19  method does not matter: it can be DNS discovery, explicitly defined services, Nomad integration, or any other method.
    20  Please refer to the [Consul documentation](https://developer.hashicorp.com/consul/docs/discovery/services) for details.
    21  
    22  ```go
    23  // Register the service in consul with the local agent.
    24  config := api.DefaultConfig()
    25  config.Address = consulAddress
    26  client, err := api.NewClient(config)
    27  if err != nil {
    28  	log.Fatalf("unable to initialize consul client: %v", err)
    29  }
    30  hostname, _ := os.Hostname()
    31  registration := &api.AgentServiceRegistration{
    32  	// These parameters are essential as allow both Consul and
    33  	// Pyroscope to reach out to the application.
    34  	Name:    serviceName,
    35  	Port:    servicePort,
    36  	Address: hostname,
    37  	// Service metadata can be propagated to Pyroscope labels,
    38  	// This allows to query profiling data in Pyroscope based on
    39  	// the service metadata attributes.
    40  	Meta: map[string]string{
    41  		"env": "dev",
    42  	},
    43  	Check: &api.AgentServiceCheck{
    44  		HTTP:     fmt.Sprintf("http://%s:%d/health", hostname, servicePort),
    45  		Interval: "10s",
    46  		Timeout:  "30s",
    47  	},
    48  }
    49  
    50  if err = client.Agent().ServiceRegister(registration); err != nil {
    51  	log.Fatalf("failed to register consul client: %v", err)
    52  }
    53  ```
    54  
    55  Pyroscope server is configured to look for profiling targets in the Consul service catalog:
    56  
    57  ```yaml
    58  ---
    59  log-level: debug
    60  scrape-configs:
    61    - job-name: consul-services
    62      enabled-profiles: [cpu, mem, goroutines, mutex, block]
    63      consul-sd-configs:
    64        - server: 'consul:8500'
    65          # Optionally specify the datacenter.
    66          datacenter: "dc1"
    67          # You may explicitly list services you want to profile.
    68          # By default, all discovered services are scraped.
    69          services:
    70            - test-service
    71  
    72      relabel-configs:
    73        # Pyroscope server needs application name (the '__name__' label)
    74        # to be provided for every profile in order to properly aggregate data.
    75        - source-labels: [__meta_consul_service]
    76          action: replace
    77          target-label: __name__
    78  
    79        # Pyroscope server is not aware of the application language and runtime,
    80        # if profiling data is pulled from the target. You can optionally specify
    81        # '__spy_name__' label to indicate it: here we take the value from the
    82        # 'pyroscope_spy_name' metadata item. By default, Go (gospy) is assumed.
    83        - source-labels:
    84            [ __meta_consul_service_metadata_pyroscope_spy_name ]
    85          action: replace
    86          target-label: __spy_name__
    87        - regex: __meta_consul_service_metadata_pyroscope_spy_name
    88          action: labeldrop
    89  
    90        # Labels that are specific to the consul service discovery (__meta_consul_*)
    91        # can be used as pyroscope labels.
    92        - source-labels: [__meta_consul_dc]
    93          action: replace
    94          target-label: consul_dc
    95  
    96        # Service metadata can be also mapped to pyroscope labels directly.
    97        - action: labelmap
    98          regex: __meta_consul_service_metadata_(.+)
    99  ```
   100  
   101  Note that our service is explicitly listed under `services` parameter, however if you have more sophisticated requirements,
   102  consider using relabeling configuration.
   103  
   104  Pyroscope uses the same discovery mechanism as Prometheus does in order to ensure smooth user experience, and it fully
   105  supports [Consul Service Discovery](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#consul_sd_config)
   106  configuration. Note that Pyroscope uses the dash character instead of the underscore character in the configuration option names.