minio/pkg/madmin/API.md
Anis Elleuch 9531cddb06 Add Profiler Admin API (#6463)
Two handlers are added to admin API to enable profiling and disable
profiling of a server in a standalone mode, or all nodes in the
distributed mode.

/minio/admin/profiling/start/{cpu,block,mem}:
  - Start profiling and return starting JSON results, e.g. one
    node is offline.

/minio/admin/profiling/download:
  - Stop the on-going profiling task
  - Stream a zip file which contains all profiling files that can
    be later inspected by go tool pprof
2018-09-18 16:46:35 -07:00

14 KiB

Golang Admin Client API Reference Slack

Initialize Minio Admin Client object.

Minio


package main

import (
    "fmt"

    "github.com/minio/minio/pkg/madmin"
)

func main() {
    // Use a secure connection.
    ssl := true

    // Initialize minio client object.
    mdmClnt, err := madmin.New("your-minio.example.com:9000", "YOUR-ACCESSKEYID", "YOUR-SECRETKEY", ssl)
    if err != nil {
        fmt.Println(err)
        return
    }

    // Fetch service status.
    st, err := mdmClnt.ServiceStatus()
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Printf("%#v\n", st)
}

Service operations Info operations Healing operations Config operations Misc
ServiceStatus ServerInfo Heal GetConfig SetCredentials
ServiceSendAction SetConfig StartProfiling
GetConfigKeys DownloadProfilingData
SetConfigKeys

1. Constructor

New(endpoint string, accessKeyID string, secretAccessKey string, ssl bool) (*AdminClient, error)

Initializes a new admin client object.

Parameters

Param Type Description
endpoint string Minio endpoint.
accessKeyID string Access key for the object storage endpoint.
secretAccessKey string Secret key for the object storage endpoint.
ssl bool Set this value to 'true' to enable secure (HTTPS) access.

2. Admin API Version

VersionInfo() (AdminAPIVersionInfo, error)

Fetch server's supported Administrative API version.

Example


	info, err := madmClnt.VersionInfo()
	if err != nil {
		log.Fatalln(err)
	}
	log.Printf("%s\n", info.Version)

3. Service operations

ServiceStatus() (ServiceStatusMetadata, error)

Fetch service status, replies disk space used, backend type and total disks offline/online (applicable in distributed mode).

Param Type Description
serviceStatus ServiceStatusMetadata Represents current server status info in following format:
Param Type Description
st.ServerVersion.Version string Server version.
st.ServerVersion.CommitID string Server commit id.
st.Uptime time.Duration Server uptime duration in seconds.

Example


   st, err := madmClnt.ServiceStatus()
   if err != nil {
   	log.Fatalln(err)
   }
   log.Printf("%#v\n", st)

ServiceSendAction(act ServiceActionValue) (error)

Sends a service action command to service - possible actions are restarting and stopping the server.

Example

       // to restart
   st, err := madmClnt.ServiceSendAction(ServiceActionValueRestart)
       // or to stop
       // st, err := madmClnt.ServiceSendAction(ServiceActionValueStop)
   if err != nil {
   	log.Fatalln(err)
   }
   log.Printf("Success")

4. Info operations

ServerInfo() ([]ServerInfo, error)

Fetches information for all cluster nodes, such as server properties, storage information, network statistics, etc.

Param Type Description
si.Addr string Address of the server the following information is retrieved from.
si.ConnStats ServerConnStats Connection statistics from the given server.
si.HTTPStats ServerHTTPStats HTTP connection statistics from the given server.
si.Properties ServerProperties Server properties such as region, notification targets.
si.Data.StorageInfo.Total int64 Total disk space.
si.Data.StorageInfo.Free int64 Free disk space.
si.Data.StorageInfo.Backend struct{} Represents backend type embedded structure.
Param Type Description
ServerProperties.Uptime time.Duration Total duration in seconds since server is running.
ServerProperties.Version string Current server version.
ServerProperties.CommitID string Current server commitID.
ServerProperties.Region string Configured server region.
ServerProperties.SQSARN []string List of notification target ARNs.
Param Type Description
ServerConnStats.TotalInputBytes uint64 Total bytes received by the server.
ServerConnStats.TotalOutputBytes uint64 Total bytes sent by the server.
Param Type Description
ServerHTTPStats.TotalHEADStats ServerHTTPMethodStats Total statistics regarding HEAD operations
ServerHTTPStats.SuccessHEADStats ServerHTTPMethodStats Total statistics regarding successful HEAD operations
ServerHTTPStats.TotalGETStats ServerHTTPMethodStats Total statistics regarding GET operations
ServerHTTPStats.SuccessGETStats ServerHTTPMethodStats Total statistics regarding successful GET operations
ServerHTTPStats.TotalPUTStats ServerHTTPMethodStats Total statistics regarding PUT operations
ServerHTTPStats.SuccessPUTStats ServerHTTPMethodStats Total statistics regarding successful PUT operations
ServerHTTPStats.TotalPOSTStats ServerHTTPMethodStats Total statistics regarding POST operations
ServerHTTPStats.SuccessPOSTStats ServerHTTPMethodStats Total statistics regarding successful POST operations
ServerHTTPStats.TotalDELETEStats ServerHTTPMethodStats Total statistics regarding DELETE operations
ServerHTTPStats.SuccessDELETEStats ServerHTTPMethodStats Total statistics regarding successful DELETE operations
Param Type Description
ServerHTTPMethodStats.Count uint64 Total number of operations.
ServerHTTPMethodStats.AvgDuration string Average duration of Count number of operations.
Param Type Description
Backend.Type BackendType Type of backend used by the server currently only FS or Erasure.
Backend.OnlineDisks int Total number of disks online (only applies to Erasure backend), is empty for FS.
Backend.OfflineDisks int Total number of disks offline (only applies to Erasure backend), is empty for FS.
Backend.StandardSCData int Data disks set for standard storage class, is empty for FS.
Backend.StandardSCParity int Parity disks set for standard storage class, is empty for FS.
Backend.RRSCData int Data disks set for reduced redundancy storage class, is empty for FS.
Backend.RRSCParity int Parity disks set for reduced redundancy storage class, is empty for FS.
Backend.Sets [][]DriveInfo Represents topology of drives in erasure coded sets.
Param Type Description
DriveInfo.UUID string Unique ID for each disk provisioned by server format.
DriveInfo.Endpoint string Endpoint location of the remote/local disk.
DriveInfo.State string Current state of the disk at endpoint.

Example


   serversInfo, err := madmClnt.ServerInfo()
   if err != nil {
   	log.Fatalln(err)
   }

   for _, peerInfo := range serversInfo {
   	log.Printf("Node: %s, Info: %v\n", peerInfo.Addr, peerInfo.Data)
   }

6. Heal operations

Heal(bucket, prefix string, healOpts HealOpts, clientToken string, forceStart bool) (start HealStartSuccess, status HealTaskStatus, err error)

Start a heal sequence that scans data under given (possible empty) bucket and prefix. The recursive bool turns on recursive traversal under the given path. dryRun does not mutate on-disk data, but performs data validation.

Two heal sequences on overlapping paths may not be initiated.

The progress of a heal should be followed using the same API Heal by providing the clientToken previously obtained from a Heal API. The server accumulates results of the heal traversal and waits for the client to receive and acknowledge them using the status request by providing clientToken.

Example


    opts := madmin.HealOpts{
            Recursive: true,
            DryRun:    false,
    }
    forceStart := false
    healPath, err := madmClnt.Heal("", "", opts, "", forceStart)
    if err != nil {
        log.Fatalln(err)
    }
    log.Printf("Heal sequence started at %s", healPath)

HealStartSuccess structure

Param Type Description
s.ClientToken string A unique token for a successfully started heal operation, this token is used to request realtime progress of the heal operation.
s.ClientAddress string Address of the client which initiated the heal operation, the client address has the form "host:port".
s.StartTime time.Time Time when heal was initially started.

HealTaskStatus structure

Param Type Description
s.Summary string Short status of heal sequence
s.FailureDetail string Error message in case of heal sequence failure
s.HealSettings HealOpts Contains the booleans set in the HealStart call
s.Items []HealResultItem Heal records for actions performed by server

HealResultItem structure

Param Type Description
ResultIndex int64 Index of the heal-result record
Type HealItemType Represents kind of heal operation in the heal record
Bucket string Bucket name
Object string Object name
Detail string Details about heal operation
DiskInfo.AvailableOn []int List of disks on which the healed entity is present and healthy
DiskInfo.HealedOn []int List of disks on which the healed entity was restored

7. Config operations

GetConfig() ([]byte, error)

Get config.json of a minio setup.

Example

    configBytes, err := madmClnt.GetConfig()
    if err != nil {
        log.Fatalf("failed due to: %v", err)
    }

    // Pretty-print config received as json.
    var buf bytes.Buffer
    err = json.Indent(buf, configBytes, "", "\t")
    if err != nil {
        log.Fatalf("failed due to: %v", err)
    }

    log.Println("config received successfully: ", string(buf.Bytes()))

SetConfig(config io.Reader) (SetConfigResult, error)

Set config.json of a minio setup and restart setup for configuration change to take effect.

Param Type Description
st.Status bool true if set-config succeeded, false otherwise.
st.NodeSummary.Name string Network address of the node.
st.NodeSummary.ErrSet bool Bool representation indicating if an error is encountered with the node.
st.NodeSummary.ErrMsg string String representation of the error (if any) on the node.

Example

    config := bytes.NewReader([]byte(`config.json contents go here`))
    result, err := madmClnt.SetConfig(config)
    if err != nil {
        log.Fatalf("failed due to: %v", err)
    }

    var buf bytes.Buffer
    enc := json.NewEncoder(&buf)
    enc.SetEscapeHTML(false)
    enc.SetIndent("", "\t")
    err = enc.Encode(result)
    if err != nil {
        log.Fatalln(err)
    }
    log.Println("SetConfig: ", string(buf.Bytes()))

GetConfigKeys(keys []string) ([]byte, error)

Get a json document which contains a set of keys and their values from config.json.

Example

    configBytes, err := madmClnt.GetConfigKeys([]string{"version", "notify.amqp.1"})
    if err != nil {
        log.Fatalf("failed due to: %v", err)
    }

    // Pretty-print config received as json.
    var buf bytes.Buffer
    err = json.Indent(buf, configBytes, "", "\t")
    if err != nil {
        log.Fatalf("failed due to: %v", err)
    }

    log.Println("config received successfully: ", string(buf.Bytes()))

SetConfigKeys(params map[string]string) error

Set a set of keys and values for Minio server or distributed setup and restart the Minio server for the new configuration changes to take effect.

Example

    err := madmClnt.SetConfigKeys(map[string]string{"notify.webhook.1": "{\"enable\": true, \"endpoint\": \"http://example.com/api\"}"})
    if err != nil {
        log.Fatalf("failed due to: %v", err)
    }

    log.Println("New configuration successfully set")

8. Misc operations

SetCredentials() error

Set new credentials of a Minio setup.

Example

    err = madmClnt.SetCredentials("YOUR-NEW-ACCESSKEY", "YOUR-NEW-SECRETKEY")
    if err != nil {
            log.Fatalln(err)
    }
    log.Println("New credentials successfully set.")

StartProfiling(profiler string) error

Ask all nodes to start profiling using the specified profiler mode

Example

    startProfilingResults, err = madmClnt.StartProfiling("cpu")
    if err != nil {
            log.Fatalln(err)
    }
    for _, result := range startProfilingResults {
        if !result.Success {
            log.Printf("Unable to start profiling on node `%s`, reason = `%s`\n", result.NodeName, result.Error)
        } else {
            log.Printf("Profiling successfully started on node `%s`\n", result.NodeName)
        }
    }

DownloadProfilingData() ([]byte, error)

Download profiling data of all nodes in a zip format.

Example

    profilingData, err := madmClnt.DownloadProfilingData()
    if err != nil {
            log.Fatalln(err)
    }

    profilingFile, err := os.Create("/tmp/profiling-data.zip")
    if err != nil {
            log.Fatal(err)
    }

    if _, err := io.Copy(profilingFile, profilingData); err != nil {
            log.Fatal(err)
    }

    if err := profilingFile.Close(); err != nil {
            log.Fatal(err)
    }

    if err := profilingData.Close(); err != nil {
            log.Fatal(err)
    }

    log.Println("Profiling data successfully downloaded.")