This is documentation for the next version of Grafana Beyla documentation. For the latest stable release, go to the latest version.

Documentationbreadcrumb arrow Beylabreadcrumb arrow Configurebreadcrumb arrow Name Resolver
Open source

Configure Beyla service host and peer name resolution

Since Beyla instruments at the protocol level, it doesn’t have access to programming language/framework information about host and peer names. Instead, Beyla has access to the IP addresses used for the communication between the services which are monitored. Therefore Beyla sources this information from metadata services, such as the Kubernetes API, or from information found in protocol headers, for example HTTP’s Host header value.

Name resolution configuration

YAML section: name_resolver

YAML

environment variable

DescriptionTypeDefault
sources

BEYLA_NAME_RESOLVER_SOURCES

A comma separated list of metadata sources to use for name resolution. More details below.list of strings[“k8s”, “rdns”]
cache_len

BEYLA_NAME_RESOLVER_CACHE_LEN

Size of the service name cache. Used to speed up reverse IP lookups.int(1024)
cache_expiry

BEYLA_NAME_RESOLVER_CACHE_TTL

Time-to-live value for the service name cache.string“5m”

The possible values for the name resolver sources are:

  • k8s. Use Kubernetes API metadata for reverse IP address lookup.
  • dns. Use the host DNS for reverse IP address lookup. This option can cause flood of DNS requests in certain situations and should be used only on services that are not exposed to the Internet.
  • rdns. Beyla tracks DNS requests for instrumentation purposes. This option uses that information to build internal cache of DNS resolved names.
  • ecs. Resolve ECS task IP addresses through the ECS inventory. Requires detected ECS metadata and AWS credentials with ecs:ListTasks and ecs:DescribeTasks permissions.
  • route53. Resolve IP addresses from configured Route53 hosted zones. Requires detected EC2 metadata and route53:ListResourceRecordSets permission for those zones.
  • gce. Resolve Compute Engine VM addresses to managed instance group names. Requires detected GCE metadata and read access to the Compute Engine inventory.
  • azure. Resolve Azure VM addresses to scale-set names. Requires detected Azure VM metadata outside Kubernetes and read access to VM, scale-set, and network-interface inventories. This source is not activated when Beyla detects Kubernetes.

Setting sources replaces the default ["k8s", "rdns"] list. Include those entries explicitly if you want to keep them alongside cloud sources. ECS names take precedence over Route53 names for the same IP.

Cloud metadata configuration

YAML section: cloud_metadata

YAML option

Environment variable

DescriptionTypeDefault
cluster_name

BEYLA_CLUSTER_NAME

Override the detected cloud cluster name, used to select the ECS cluster.stringDetected
region

BEYLA_CLOUD_REGION

Override the detected cloud region.stringDetected
refresh_interval

BEYLA_CLOUD_META_REFRESH_INTERVAL

Cloud inventory refresh interval. Must be greater than 0.Duration30s
route53.hosted_zone_ids

BEYLA_NAME_RESOLVER_ROUTE53_HOSTED_ZONE_IDS

Hosted zones to query. Required when route53 is enabled. Environment values are comma-separated.list of strings[]
route53.refresh_interval

BEYLA_NAME_RESOLVER_ROUTE53_REFRESH_INTERVAL

Independent Route53 polling interval. Must be greater than 0.Duration5m

For an ECS deployment:

YAML 
name_resolver:
  sources: ["k8s", "rdns", "ecs"]
cloud_metadata:
  cluster_name: production
  region: eu-central-1
  refresh_interval: 30s

The cluster and region overrides supply missing inventory scope or replace detected values. Cloud sources also require the corresponding cloud environment to be detected; setting an override alone does not activate a source.

For Route53:

YAML 
name_resolver:
  sources: ["k8s", "rdns", "route53"]
cloud_metadata:
  region: eu-central-1
  route53:
    hosted_zone_ids: ["Z0123456789EXAMPLE"]
    refresh_interval: 5m

Beyla reads A and AAAA records containing IP addresses from the specified zones. Names use lowercase and are exported without the trailing dot. Alias records, CNAME records, and wildcard names are skipped. Choose zones that describe the services you want Beyla to resolve.

Route53 polling uses its own refresh interval, with jitter to spread requests and backoff when AWS throttles the client.

Google Cloud and Azure discovery scopes

Beyla exposes provider scope settings under name_resolver. Empty values use the scope detected from cloud metadata.

YAML option

Environment variable

DescriptionTypeDefault
gce.project_id

BEYLA_NAME_RESOLVER_GCE_PROJECT_ID

Compute Engine project to query.stringDetected
gce.zone

BEYLA_NAME_RESOLVER_GCE_ZONE

Zone containing the managed instance groups.stringDetected
gce.endpoint

BEYLA_NAME_RESOLVER_GCE_ENDPOINT

Compute API base URL override for a proxy or emulator.URLGoogle Compute API
azure.subscription_id

BEYLA_NAME_RESOLVER_AZURE_SUBSCRIPTION_ID

Azure subscription to query.stringDetected
azure.resource_group

BEYLA_NAME_RESOLVER_AZURE_RESOURCE_GROUP

Resource group containing the scale sets.stringDetected

For example, resolve GCE managed instance groups:

YAML 
name_resolver:
  sources: ["k8s", "rdns", "gce"]
  gce:
    project_id: production-project
    zone: europe-west3-a

The Google client uses application default credentials. The Compute Viewer role provides read access to the inventory. Scope discovery covers managed instance groups in the configured zone.

For Azure scale sets:

YAML 
name_resolver:
  sources: ["k8s", "rdns", "azure"]
  azure:
    subscription_id: "00000000-0000-0000-0000-000000000000"
    resource_group: production

The Azure client uses the default Azure credential chain. The Reader role at the relevant scope provides the required read access. Both Uniform and Flexible scale sets are supported. The cloud inventory refresh interval is controlled by cloud_metadata.refresh_interval.