usage

Documentation

Overview

Package usage provides information and interaction with the SimpleTenantUsage extension for the OpenStack Compute service.

Due to the way the API responses are formatted, it is not recommended to query by using the AllPages convenience method. Instead, use the EachPage method to view each result page-by-page.

This is because the usage calculations are done _per page_ and not as an aggregated total of the entire usage set.

Example to Retrieve Usage for a Single Tenant:

start := time.Date(2017, 01, 21, 10, 4, 20, 0, time.UTC)
end := time.Date(2017, 01, 21, 10, 4, 20, 0, time.UTC)

singleTenantOpts := usage.SingleTenantOpts{
	Start: &start,
	End: &end,
}

err := usage.SingleTenant(computeClient, tenantID, singleTenantOpts).EachPage(func(page pagination.Page) (bool, error) {
	tenantUsage, err := usage.ExtractSingleTenant(page)
	if err != nil {
		return false, err
	}

	fmt.Printf("%+v\n", tenantUsage)

	return true, nil
})

if err != nil {
	panic(err)
}

Example to Retrieve Usage for All Tenants:

allTenantsOpts := usage.AllTenantsOpts{
	Detailed: true,
}

err := usage.AllTenants(computeClient, allTenantsOpts).EachPage(func(page pagination.Page) (bool, error) {
	allTenantsUsage, err := usage.ExtractAllTenants(page)
	if err != nil {
		return false, err
	}

	fmt.Printf("%+v\n", allTenantsUsage)

	return true, nil
})

if err != nil {
	panic(err)
}

Index

• func AllTenants(client *gophercloud.ServiceClient, opts AllTenantsOptsBuilder) pagination.Pager
• func SingleTenant(client *gophercloud.ServiceClient, tenantID string, ...) pagination.Pager
• type AllTenantsOpts
  • func (opts AllTenantsOpts) ToUsageAllTenantsQuery() (string, error)
• type AllTenantsOptsBuilder
• type AllTenantsPage
  • func (r AllTenantsPage) IsEmpty() (bool, error)
  • func (r AllTenantsPage) NextPageURL() (string, error)
• type ServerUsage
  • func (u *ServerUsage) UnmarshalJSON(b []byte) error
• type SingleTenantOpts
  • func (opts SingleTenantOpts) ToUsageSingleTenantQuery() (string, error)
• type SingleTenantOptsBuilder
• type SingleTenantPage
  • func (r SingleTenantPage) IsEmpty() (bool, error)
  • func (r SingleTenantPage) NextPageURL() (string, error)
• type TenantUsage
  • func ExtractAllTenants(page pagination.Page) ([]TenantUsage, error)
  • func ExtractSingleTenant(page pagination.Page) (*TenantUsage, error)
  • func (u *TenantUsage) UnmarshalJSON(b []byte) error

Functions

func AllTenants

func AllTenants(client *gophercloud.ServiceClient, opts AllTenantsOptsBuilder) pagination.Pager

AllTenants returns usage data about all tenants.

func SingleTenant

func SingleTenant(client *gophercloud.ServiceClient, tenantID string, opts SingleTenantOptsBuilder) pagination.Pager

SingleTenant returns usage data about a single tenant.

Types

type AllTenantsOpts

type AllTenantsOpts struct {
	// Detailed will return detailed results.
	Detailed bool

	// The ending time to calculate usage statistics on compute and storage resources.
	End *time.Time `q:"end"`

	// The beginning time to calculate usage statistics on compute and storage resources.
	Start *time.Time `q:"start"`

	// Limit limits the amount of results returned by the API.
	// This requires the client to be set to microversion 2.40 or later.
	Limit int `q:"limit"`

	// Marker instructs the API call where to start listing from.
	// This requires the client to be set to microversion 2.40 or later.
	Marker string `q:"marker"`
}

AllTenantsOpts are options for fetching usage of all tenants.

func (AllTenantsOpts) ToUsageAllTenantsQuery

func (opts AllTenantsOpts) ToUsageAllTenantsQuery() (string, error)

ToUsageAllTenantsQuery formats a AllTenantsOpts into a query string.

type AllTenantsOptsBuilder

type AllTenantsOptsBuilder interface {
	ToUsageAllTenantsQuery() (string, error)
}

AllTenantsOptsBuilder allows extensions to add additional parameters to the AllTenants request.

type AllTenantsPage

type AllTenantsPage struct {
	pagination.LinkedPageBase
}

AllTenantsPage stores a single, only page of TenantUsage results from a AllTenants call.

func (AllTenantsPage) IsEmpty

func (r AllTenantsPage) IsEmpty() (bool, error)

IsEmpty determines whether or not an AllTenantsPage is empty.

func (AllTenantsPage) NextPageURL

func (r AllTenantsPage) NextPageURL() (string, error)

NextPageURL uses the response's embedded link reference to navigate to the next page of results.

type ServerUsage

type ServerUsage struct {
	// EndedAt is the date and time when the server was deleted
	EndedAt time.Time `json:"-"`

	// Flavor is the display name of a flavor
	Flavor string `json:"flavor"`

	// Hours is the duration that the server exists in hours
	Hours float64 `json:"hours"`

	// InstanceID is the UUID of the instance
	InstanceID string `json:"instance_id"`

	// LocalGB is the sum of the root disk size of the server and the ephemeral disk size of it (in GiB)
	LocalGB int `json:"local_gb"`

	// MemoryMB is the memory size of the server (in MB)
	MemoryMB int `json:"memory_mb"`

	// Name is the name assigned to the server when it was created
	Name string `json:"name"`

	// StartedAt is the date and time when the server was started
	StartedAt time.Time `json:"-"`

	// State is the VM power state
	State string `json:"state"`

	// TenantID is the UUID of the tenant in a multi-tenancy cloud
	TenantID string `json:"tenant_id"`

	// Uptime is the uptime of the server in seconds
	Uptime int `json:"uptime"`

	// VCPUs is the number of virtual CPUs that the server uses
	VCPUs int `json:"vcpus"`
}

ServerUsage is a detailed set of information about a specific instance inside a tenant

func (*ServerUsage) UnmarshalJSON

func (u *ServerUsage) UnmarshalJSON(b []byte) error

UnmarshalJSON sets *u to a copy of data.

type SingleTenantOpts

type SingleTenantOpts struct {
	// The ending time to calculate usage statistics on compute and storage resources.
	End *time.Time `q:"end"`

	// The beginning time to calculate usage statistics on compute and storage resources.
	Start *time.Time `q:"start"`

	// Limit limits the amount of results returned by the API.
	// This requires the client to be set to microversion 2.40 or later.
	Limit int `q:"limit"`

	// Marker instructs the API call where to start listing from.
	// This requires the client to be set to microversion 2.40 or later.
	Marker string `q:"marker"`
}

SingleTenantOpts are options for fetching usage of a single tenant.

func (SingleTenantOpts) ToUsageSingleTenantQuery

func (opts SingleTenantOpts) ToUsageSingleTenantQuery() (string, error)

ToUsageSingleTenantQuery formats a SingleTenantOpts into a query string.

type SingleTenantOptsBuilder

type SingleTenantOptsBuilder interface {
	ToUsageSingleTenantQuery() (string, error)
}

SingleTenantOptsBuilder allows extensions to add additional parameters to the SingleTenant request.

type SingleTenantPage

type SingleTenantPage struct {
	pagination.LinkedPageBase
}

SingleTenantPage stores a single, only page of TenantUsage results from a SingleTenant call.

func (SingleTenantPage) IsEmpty

func (r SingleTenantPage) IsEmpty() (bool, error)

IsEmpty determines whether or not a SingleTenantPage is empty.

func (SingleTenantPage) NextPageURL

func (r SingleTenantPage) NextPageURL() (string, error)

NextPageURL uses the response's embedded link reference to navigate to the next page of results.

type TenantUsage

type TenantUsage struct {
	// ServerUsages is an array of ServerUsage maps
	ServerUsages []ServerUsage `json:"server_usages"`

	// Start is the beginning time to calculate usage statistics on compute and storage resources
	Start time.Time `json:"-"`

	// Stop is the ending time to calculate usage statistics on compute and storage resources
	Stop time.Time `json:"-"`

	// TenantID is the ID of the tenant whose usage is being reported on
	TenantID string `json:"tenant_id"`

	// TotalHours is the total duration that servers exist (in hours)
	TotalHours float64 `json:"total_hours"`

	// TotalLocalGBUsage multiplies the server disk size (in GiB) by hours the server exists, and then adding that all together for each server
	TotalLocalGBUsage float64 `json:"total_local_gb_usage"`

	// TotalMemoryMBUsage multiplies the server memory size (in MB) by hours the server exists, and then adding that all together for each server
	TotalMemoryMBUsage float64 `json:"total_memory_mb_usage"`

	// TotalVCPUsUsage multiplies the number of virtual CPUs of the server by hours the server exists, and then adding that all together for each server
	TotalVCPUsUsage float64 `json:"total_vcpus_usage"`
}

TenantUsage is a set of usage information about a tenant over the sampling window

func ExtractAllTenants

func ExtractAllTenants(page pagination.Page) ([]TenantUsage, error)

ExtractAllTenants interprets a AllTenantsPage as a TenantUsage result.

func ExtractSingleTenant

func ExtractSingleTenant(page pagination.Page) (*TenantUsage, error)

ExtractSingleTenant interprets a SingleTenantPage as a TenantUsage result.

func (*TenantUsage) UnmarshalJSON

func (u *TenantUsage) UnmarshalJSON(b []byte) error

UnmarshalJSON sets *u to a copy of data.